From 4c74c72c2913d173073d3e2f7df3ec49c8e871d8 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 17 Jan 2024 15:22:07 -0600 Subject: [PATCH] (AB#200851) Update for `alpha.4` release This change brings over the updates to the reference documentation and the changelog from the `alpha.4` release of DSCv3. It also updates the TOC to enable navigating to every reference document. - Fixes AB#200851 --- dsc/docs-conceptual/dsc-3.0/changelog.md | 206 +++++++++++++++- .../reference/cli/completer/command.md | 108 ++++++++ .../dsc-3.0/reference/cli/config/get.md | 30 ++- .../dsc-3.0/reference/cli/config/set.md | 30 ++- .../dsc-3.0/reference/cli/config/test.md | 30 ++- .../dsc-3.0/reference/cli/dsc.md | 75 +++++- .../reference/schemas/config/document.md | 45 +++- .../schemas/config/functions/base64.md | 111 +++++++++ .../schemas/config/functions/concat.md | 82 +++++++ .../schemas/config/functions/overview.md | 232 ++++++++++++++++++ .../schemas/config/functions/resourceId.md | 111 +++++++++ .../reference/schemas/config/parameter.md | 4 +- .../reference/schemas/config/resource.md | 30 ++- .../reference/schemas/definitions/message.md | 4 +- .../definitions/parameters/dataTypes.md | 4 +- .../schemas/definitions/resourceType.md | 4 +- .../reference/schemas/outputs/config/get.md | 4 +- .../reference/schemas/outputs/config/set.md | 4 +- .../reference/schemas/outputs/config/test.md | 4 +- .../reference/schemas/outputs/resource/get.md | 4 +- .../schemas/outputs/resource/list.md | 4 +- .../reference/schemas/outputs/resource/set.md | 4 +- .../schemas/outputs/resource/test.md | 4 +- .../schemas/resource/manifest/export.md | 4 +- .../schemas/resource/manifest/get.md | 4 +- .../schemas/resource/manifest/provider.md | 4 +- .../schemas/resource/manifest/root.md | 34 ++- .../resource/manifest/schema/embedded.md | 27 +- .../resource/manifest/schema/property.md | 4 +- .../schemas/resource/manifest/set.md | 4 +- .../schemas/resource/manifest/test.md | 4 +- .../schemas/resource/manifest/validate.md | 4 +- .../schemas/resource/properties/ensure.md | 9 +- .../schemas/resource/properties/exist.md | 49 ++++ .../resource/properties/inDesiredState.md | 6 +- .../schemas/resource/properties/overview.md | 17 +- .../schemas/resource/properties/purge.md | 6 +- .../resource/properties/rebootRequested.md | 6 +- dsc/docs-conceptual/dsc-3.0/toc.yml | 22 ++ 39 files changed, 1226 insertions(+), 112 deletions(-) create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/cli/completer/command.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/overview.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/resourceId.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md diff --git a/dsc/docs-conceptual/dsc-3.0/changelog.md b/dsc/docs-conceptual/dsc-3.0/changelog.md index 984f532..4131d4f 100644 --- a/dsc/docs-conceptual/dsc-3.0/changelog.md +++ b/dsc/docs-conceptual/dsc-3.0/changelog.md @@ -2,11 +2,13 @@ title: "Desired State Configuration changelog" description: >- A log of the changes for releases of DSCv3. -ms.date: 09/27/2023 +ms.date: 01/17/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]. @@ -20,10 +22,176 @@ This section includes a summary of user-facing changes since the last release. F changes since the last release, see the [diff on GitHub][unreleased]. -[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.3...main +[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...main +## [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 +in this release, see the [diff on GitHub][compare-v3.0.0-alpha.4]. + + +[release-v3.0.0-alpha.4]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-alpha.4 "Link to the DSC v3.0.0-alpha.4 release on GitHub" +[compare-v3.0.0-alpha.4]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.3...v3.0.0-alpha.4 + +### Changed + +- 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 + 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. + +
Related work items + + - Issues: [#202][#202] + - PRs: [#206][#206] + +
+ +- Updated the `Microsoft.Windows/Registry` resource to use the `_exist` property instead of + `_ensure` and updated the output to be idiomatic for a DSC Resource. + +
Related work items + + - Issues: [#162][#162] + - PRs: [#206][#206] + +
+ +- When a user presses the Ctrl+C key combination, DSC now recursively + terminates all child processes before exiting. This helps prevent dangling processes that were + previously unhandled by the interrupt event. + +
Related work items + + - PRs: [#213][#213] + +
+ +### Added + +- Added the [--input][24] and [--input-file][25] global options to the root `dsc` command. Now, you + can pass input to DSC from a variable or file instead of piping from stdin. + +
Related work items + + - Issues: [#130][#130] + - PRs: [#217][#217] + +
+ +- Added the `arg` value as an option for defining how a command-based DSC Resource expects to + receive input. This enables resource authors to define resources that handle DSC passing the + instance JSON as an argument. + +
Related work items + + - PRs: [#213][#213] + +
+ +- Added the new [completer][26] 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 + + - Issues: [#186][#186] + - PRs: [#216][#216] + +
+ +- DSC now emits log messages to the stderr stream. This can make it easier to understand what DSC + is doing. This doesn't affect the data output. By default, DSC emits errors, warnings, and + informational messages, but not debug or trace messaging. You can control the level of the + logging with the new [--logging-level][27] option on the root `dsc` command. + +
Related work items + + - Issues: + - [#107][#107] + - [#158][#158] + - PRs: + - [#211][#211] + - [#248][#248] + +
+ +- Added optimizations for the resource discovery process that runs before most `dsc` commands. + These optimizations significantly reduce the command execution duration, especially for the + `dsc resource *` commands, which rarely need to run a full discovery for resources. + +
Related work items + + - Issues: [#173][#173] + - PRs: [#240][#240] + +
+ +- 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. + + > [!NOTE] + > The `resourceId` function has been reimplemented as a document function instead of a special + > case, but it has the same functionality and parameters. + +
Related work items + + - Issues: [#57][#57] + - PRs: + - [#241][#241] + - [#252][#252] + +
+ +### Fixed + +- The `--format` option now works as users expect when the output is redirected or saved to a + variable. Before this fix, DSC always returned JSON output, even when the user wanted to save + the output as YAML. With this fix, the specified format is respected. + +
Related work items + + - PRs: [#215][#215] + +
+ +- The `DSC/PowerShellGroup` resource now correctly returns the _labels_ for enumerations instead of + their integer value, making it easier to understand and compare results. + +
Related work items + + - Issues: [#159][#159] + - PRs: [#208][#208] + +
+ +- DSC no longer terminates during discovery when a resource errors unless the erroring resource is + being used for the command. DSC still terminates on a resource error during discovery under the + following conditions: + + - When the erroring resource type is the same as the value of the `--resource` option for a + `dsc resource *` command. + - When an instance in the configuration document uses the erroring resource type for a + `dsc config *` command. + + DSC emits the resource errors during discovery as warning messages for the `dsc resource list` + command. In all other cases, DSC emits the errors as debug messages. + +
Related work items + + - Issues: [#121][#121] + - PRs: [#240][#240] + +
+ ## [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 @@ -291,24 +459,58 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [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 +[24]: reference/cli/dsc.md#-i---input +[25]: reference/cli/dsc.md#-p---input-file +[26]: reference/cli/completer/command.md +[27]: reference/cli/dsc.md#-l---logging-level +[28]: reference/schemas/config/functions/overview.md +[29]: reference/schemas/config/functions/base64.md +[30]: reference/schemas/config/functions/concat.md +[31]: reference/schemas/config/functions/resourceId.md + +[#107]: https://github.com/PowerShell/DSC/issues/107 +[#121]: https://github.com/PowerShell/DSC/issues/121 [#127]: https://github.com/PowerShell/DSC/issues/127 +[#130]: https://github.com/PowerShell/DSC/issues/130 [#133]: https://github.com/PowerShell/DSC/issues/133 [#150]: https://github.com/PowerShell/DSC/issues/150 [#156]: https://github.com/PowerShell/DSC/issues/156 +[#158]: https://github.com/PowerShell/DSC/issues/158 +[#159]: https://github.com/PowerShell/DSC/issues/159 +[#162]: https://github.com/PowerShell/DSC/issues/162 [#163]: https://github.com/PowerShell/DSC/issues/163 [#168]: https://github.com/PowerShell/DSC/issues/168 [#171]: https://github.com/PowerShell/DSC/issues/171 [#172]: https://github.com/PowerShell/DSC/issues/172 +[#173]: https://github.com/PowerShell/DSC/issues/173 [#174]: https://github.com/PowerShell/DSC/issues/174 [#175]: https://github.com/PowerShell/DSC/issues/175 [#176]: https://github.com/PowerShell/DSC/issues/176 [#177]: https://github.com/PowerShell/DSC/issues/177 [#181]: https://github.com/PowerShell/DSC/issues/181 [#182]: https://github.com/PowerShell/DSC/issues/182 +[#186]: https://github.com/PowerShell/DSC/issues/186 [#197]: https://github.com/PowerShell/DSC/issues/197 [#198]: https://github.com/PowerShell/DSC/issues/198 [#199]: https://github.com/PowerShell/DSC/issues/199 +[#202]: https://github.com/PowerShell/DSC/issues/202 +[#206]: https://github.com/PowerShell/DSC/issues/206 +[#208]: https://github.com/PowerShell/DSC/issues/208 +[#211]: https://github.com/PowerShell/DSC/issues/211 +[#213]: https://github.com/PowerShell/DSC/issues/213 +[#215]: https://github.com/PowerShell/DSC/issues/215 +[#216]: https://github.com/PowerShell/DSC/issues/216 +[#217]: https://github.com/PowerShell/DSC/issues/217 +[#240]: https://github.com/PowerShell/DSC/issues/240 +[#241]: https://github.com/PowerShell/DSC/issues/241 +[#248]: https://github.com/PowerShell/DSC/issues/248 +[#252]: https://github.com/PowerShell/DSC/issues/252 [#45]: https://github.com/PowerShell/DSC/issues/45 +[#57]: https://github.com/PowerShell/DSC/issues/57 [#73]: https://github.com/PowerShell/DSC/issues/73 [#98]: https://github.com/PowerShell/DSC/issues/98 diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/completer/command.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/completer/command.md new file mode 100644 index 0000000..84d2ce4 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/completer/command.md @@ -0,0 +1,108 @@ +--- +description: Command line reference for the 'dsc completer' command +ms.date: 01/17/2024 +ms.topic: reference +title: dsc completer +--- + +# dsc completer + +## Synopsis + +Generates a shell completion script. + +## Syntax + +```sh +dsc completer [Options] +``` + +## Description + +The `completer` command returns a shell script that, when executed, registers completions for the +given shell. DSC can generate completion scripts for the following shells: + +- [Bourne Again SHell (BASH)][01] +- [Elvish][02] +- [Friendly Interactive SHell (fish)][03] +- [PowerShell][04] +- [Z SHell (ZSH)][05] + +The output for this command is the script itself. To register completions for DSC, execute the +script. + +> [!WARNING] +> Always review scripts before executing them, especially in an elevated execution context. + +## Examples + +### Example 1 - Register completions for Bash + +```sh +completer=~/dsc_completion.bash +# Export the completion script +dsc completer bash > $completer +# Review the completion script +cat $completer +# Add the completion script to your profile +echo "source $completer" >> ~/.bashrc +# Execute the completion script to register completions for this session +source $completer +``` + +### Example 2 - Register completions for PowerShell + +```powershell +$Completer = '~/dsc_completion.ps1' +# Export the completion script +dsc completer powershell | Out-File $Completer +# Review the completion script +Get-Content $completer +# Add the completion script to your profile +Add-Content -Path $PROFILE ". $Completer" +# Execute the completion script to register completions for this session +. $Completer +``` + +## Arguments + +### SHELL + +This argument is mandatory for the `completer` command. The value for this option determines which +shell the application returns a completion script for: + +- `bash` - [Bourne Again SHell (BASH)][01] +- `elvish` - [Elvish][02] +- `fish` - [Friendly Interactive SHell (fish)][03] +- `powershell` - [PowerShell][04] +- `zsh` - [Z SHell (ZSH)][05] + +```yaml +Type: String +Mandatory: true +ValidValues: [ + bash, + elvish, + fish, + powershell, + zsh, + ] +``` + +## Options + +### -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 +``` + +[01]: https://www.gnu.org/software/bash/ +[02]: https://elv.sh/ +[03]: https://fishshell.com/ +[04]: https://learn.microsoft.com/powershell/scripting/overview +[05]: https://zsh.sourceforge.io/ 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 fe6130b..36e4755 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: 08/04/2023 +ms.date: 01/17/2024 ms.topic: reference title: dsc config get --- @@ -34,12 +34,12 @@ document saved as `example.dsc.config.yaml`. ```yaml # example.dsc.config.yaml -$schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json resources: - name: Windows only type: DSC/AssertionGroup properties: - $schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json resources: - name: os type: Microsoft/OSInfo @@ -58,6 +58,24 @@ resources: cat ./example.dsc.config.yaml | dsc config get ``` +### Example 2 - Passing a file to read as the configuration document + +The command uses the [--input-file][01] global option to retrieve the resource instances defined in +the `example.dsc.config.yaml` file. + +```sh +dsc --input-file ./example.dsc.config.yaml config get +``` + +### Example 3 - Passing a configuration document as a variable + +The command uses the [--input][02] global option to retrieve the resource instances defined in a +configuration document stored in the `$desired` variable. + +```sh +dsc --input $desired config get +``` + ## Options ### -h, --help @@ -74,6 +92,8 @@ Mandatory: false This command returns JSON output that includes whether the operation or any resources raised any errors, the collection of messages emitted during the operation, and the get operation results for -every instance. For more information, see [dsc config get result schema][01]. +every instance. For more information, see [dsc config get result schema][03]. -[01]: ../../schemas/outputs/config/get.md +[01]: ../dsc.md#-p---input-file +[02]: ../dsc.md#-i---input +[03]: ../../schemas/outputs/config/get.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md index 223d1be..77e63d1 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: 08/04/2023 +ms.date: 01/17/2024 ms.topic: reference title: dsc config set --- @@ -35,12 +35,12 @@ The command inspects the resource instances defined in the configuration documen ```yaml # example.dsc.config.yaml -$schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json resources: - name: Windows only type: DSC/AssertionGroup properties: - $schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json resources: - name: os type: Microsoft/OSInfo @@ -59,6 +59,24 @@ resources: cat ./example.dsc.config.yaml | dsc config set ``` +### Example 2 - Passing a file to read as the configuration document + +The command uses the [--input-file][01] global option to enforce the configuration defined in +the `example.dsc.config.yaml` file. + +```sh +dsc --input-file ./example.dsc.config.yaml config set +``` + +### Example 3 - Passing a configuration document as a variable + +The command uses the [--input][02] global option to enforce the configuration stored in the +`$desired` variable. + +```sh +dsc --input $desired config set +``` + ## Options ### -h, --help @@ -75,6 +93,8 @@ Mandatory: false This command returns JSON output that includes whether the operation or any resources raised any errors, the collection of messages emitted during the operation, and the set operation results for -every instance. For more information, see [dsc config get result schema][01]. +every instance. For more information, see [dsc config get result schema][03]. -[01]: ../../schemas/outputs/config/set.md +[01]: ../dsc.md#-p---input-file +[02]: ../dsc.md#-i---input +[03]: ../../schemas/outputs/config/set.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md index 6cd072c..995d6eb 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: 08/04/2023 +ms.date: 01/17/2024 ms.topic: reference title: dsc config test --- @@ -34,12 +34,12 @@ resource instances defined in the configuration document saved as `example.dsc.c ```yaml # example.dsc.config.yaml -$schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json resources: - name: Windows only type: DSC/AssertionGroup properties: - $schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json resources: - name: os type: Microsoft/OSInfo @@ -58,6 +58,24 @@ resources: cat ./example.dsc.config.yaml | dsc config test ``` +### Example 2 - Passing a file to read as the configuration document + +The command uses the [--input-file][01] global option to validate the configuration defined in +the `example.dsc.config.yaml` file. + +```sh +dsc --input-file ./example.dsc.config.yaml config test +``` + +### Example 3 - Passing a configuration document as a variable + +The command uses the [--input][02] global option to validate the configuration stored in the +`$desired` variable. + +```sh +dsc --input $desired config test +``` + ## Options ### -h, --help @@ -74,6 +92,8 @@ Mandatory: false This command returns JSON output that includes whether the operation or any resources raised any errors, the collection of messages emitted during the operation, and the test operation results for -every instance. For more information, see [dsc config test result schema][01]. +every instance. For more information, see [dsc config test result schema][03]. -[01]: ../../schemas/outputs/config/test.md +[01]: ../dsc.md#-p---input-file +[02]: ../dsc.md#-i---input +[03]: ../../schemas/outputs/config/test.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/dsc.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/dsc.md index c0e93b8..8f0b622 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/dsc.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/dsc.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc' command -ms.date: 09/06/2023 +ms.date: 01/17/2024 ms.topic: reference title: dsc --- @@ -19,6 +19,11 @@ dsc [Options] ## Commands +### completer + +The `completer` command returns a shell script that, when executed, registers completions for the +given shell. For more information, see [completer][01]. + ### config The `config` command manages a DSC Configuration document. You can use it to: @@ -27,7 +32,7 @@ The `config` command manages a DSC Configuration document. You can use it to: - Test whether a configuration is in the desired state. - Set a configuration to the desired state. -For more information, see [config][01]. +For more information, see [config][02]. ### resource @@ -39,12 +44,12 @@ The `resource` command manages a DSC Resource. You can use it to: - Test whether a resource instance is in the desired state. - Set a resource instance to the desired state. -For more information, see [resource][02] +For more information, see [resource][03] ### schema The `schema` command returns the JSON schema for a specific DSC type. For more information, see -[schema][03]. +[schema][04]. ### help @@ -89,6 +94,61 @@ Type: Boolean Mandatory: false ``` +### -i, --input + +Defines input for the command as a string instead of piping input from stdin. This option is +mutually exclusive with the `--input-file` option. When you use this option, DSC ignores any input +from stdin. + +To pass input for a command or subcommand, specify this option before the command, like +`dsc --input $desired resource test`. + +```yaml +Type: String +Mandatory: false +``` + +### -l, --logging-level + +Defines the minimum log level DSC should emit during an operation. Messages in DSC are categorized +by their log level. + +The following list shows the valid log levels from highest to lowest level. When this option is +set to any value in the list, DSC emits messages at that level and above. + +- `Error` +- `Warning` +- `Info` (default) +- `Debug` +- `Trace` + +For example, when the log level is `Debug`, DSC emits messages for every log level except `Trace`. +Dsc emits only error messages when the log level is `Error`. DSC ignores every message with a lower +log level. + +```yaml +Type: String +Mandatory: false +DefaultValue: Info +ValidValues: [Error, Warning, Info, Debug, Trace] +``` + +### -p, --input-file + +Defines the path to a text file to read as input for the command instead of piping input from +stdin. This option is mutually exclusive with the `--input` option. When you use this option, DSC +ignores any input from stdin. + +To pass a file to read as input for a command or subcommand, specify this option before the +command, like `dsc --input-file web.dsc.config.yaml config set`. + +If the specified file doesn't exist, DSC raises an error. + +```yaml +Type: String +Mandatory: false +``` + ### -V, --version Displays the version of the application. When you specify this option, the application ignores all @@ -124,6 +184,7 @@ execution of the command. | `5` | The command failed because a resource definition or instance value was invalid against its JSON schema. | | `6` | The command was cancelled by a Ctrl+C interruption. | -[01]: config/command.md -[02]: resource/command.md -[03]: schema/command.md +[01]: completer/command.md +[02]: config/command.md +[03]: resource/command.md +[04]: schema/command.md 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 0d699e6..3665b2e 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: 08/04/2023 +ms.date: 01/17/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/08/config/document.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json Type: object ``` @@ -31,6 +31,9 @@ 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`. +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] + The rest of this document describes the schema DSC uses to validation configuration documents. @@ -50,16 +53,46 @@ Every configuration document must include these properties: ### $schema -The `$schema` property indicates the canonical URI for the version of this schema that the document +The `$schema` property indicates the canonical URL for the version of this schema that the document adheres to. DSC uses this property when validating the configuration document before any configuration operations. +For every version of the schema, there are three valid urls: + +- `.../config/document.json` + + The URL to the canonical non-bundled schema. When it's used for validation, the validating client + needs to retrieve this schema and every schema it references. + +- `.../bundled/config/document.json` + + The URL to the bundled schema. When it's used for validation, the validating client only needs to + retrieve this schema. + + This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can still + validate the document when it uses this schema, other tools may error or behave in unexpected + ways. + +- `.../bundled/config/document.vscode.json` + + The URL to the enhanced authoring schema. This schema is much larger than the other schemas, as + it includes additional definitions that provide contextual help and snippets that the others + don't include. + + This schema uses keywords that are only recognized by VS Code. While DSC can still validate the + document when it uses this schema, other tools may error or behave in unexpected ways. + ```yaml Type: string Required: true Format: URI ValidValues: [ + 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 https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json ] ``` @@ -93,7 +126,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/08/config/document.parameter.json +ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.parameter.json ``` ### variables @@ -129,9 +162,11 @@ 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/08/config/document.resource.json +ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.resource.json ``` + +[01]: functions/resourceId.md [02]: parameter.md 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 new file mode 100644 index 0000000..573e025 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64.md @@ -0,0 +1,111 @@ +--- +description: Reference for the 'base64' DSC configuration document function +ms.date: 01/17/2024 +ms.topic: reference +title: base64 +--- + +# base64 + +## Synopsis + +Returns the base64 representation of an input string. + +## Syntax + +```Syntax +base64() +``` + +## Description + +The `base64()` function returns the [base64][01] representation of an input string. Passing data +encoded as base64 can reduce errors in passing data, especially when different tools require +different escape characters. + +## Examples + +### Example 1 - Convert a string to base64 + +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 +resources: + - name: Echo 'abc' in base64 + type: Test/Echo + properties: + text: "[base64('abc')]" +``` + +```bash +dsc --input-file base64.example.1.dsc.config.yaml config get +``` + +```yaml +results: +- name: Echo 'abc' in base64 + type: Test/Echo + result: + actualState: + text: YWJj +messages: [] +hadErrors: false +``` + +### Example 2 - Convert a concatenated string to base64 + +The configuration uses the [concat()][02] function inside the `base64()` function to combine the +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 +resources: + - name: Echo concatenated 'a', 'b', 'c' in base64 + type: Test/Echo + properties: + text: "[base64(concat('a', 'b', 'c'))]" +``` + +```bash +dsc --input-file base64.example.2.dsc.config.yaml config get +``` + +```yaml +results: +- name: Echo concatenated 'a', 'b', 'c' in base64 + type: Test/Echo + result: + actualState: + text: YWJj +messages: [] +hadErrors: false +``` + +## Parameters + +### 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. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The output of the function is the base64 representation of the **inputString** value. + +```yaml +Type: string +``` + + +[01]: https://en.wikipedia.org/wiki/Base64 +[02]: concat.md 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 new file mode 100644 index 0000000..8218480 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md @@ -0,0 +1,82 @@ +--- +description: Reference for the 'concat' DSC configuration document function +ms.date: 01/17/2024 +ms.topic: reference +title: concat +--- + +# concat + +## Synopsis + +Returns a string of combined values. + +## Syntax + +```Syntax +concat(, [, ...]) +``` + +## Description + +The `concat()` function combines multiple values and returns the concatenated values as a single +string. Separate each value with a comma. The `concat()` function is variadic. You must pass at +least two values to the function. The function can accept any number of arguments. + +The function concatenates the input values without any joining character. It accepts only strings +and integers as input values. + +## Examples + +### Example 1 - Concatenate strings + +The configuration uses the `concat()` function to join the string `abc` and the integer `123` + +```yaml +# concat.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +resources: + - name: Echo 'abc123' + type: Test/Echo + properties: + text: "[concat('abc', 123)]" +``` + +```bash +dsc --input-file concat.example.1.dsc.config.yaml config get +``` + +```yaml +results: +- name: Echo 'abc123' + type: Test/Echo + result: + actualState: + text: abc123 +messages: [] +hadErrors: false +``` + +## Parameters + +### inputValue + +A value to concatenate. Each value must be either a string or an integer. The values are added to +the output string in the same order you pass them to the function. + +```yaml +Type: [string, integer] +Required: true +MinimumCount: 2 +MaximumCount: 18446744073709551615 +``` + +## Output + +The output of the function is a single string with every **inputValue** concatenated together. + +```yaml +Type: string +``` + + 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 new file mode 100644 index 0000000..5cd2187 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/overview.md @@ -0,0 +1,232 @@ +--- +description: Reference for available functions in a Desired State Configuration document. +ms.date: 01/17/2024 +ms.topic: reference +title: DSC Configuration document functions reference +--- + +# DSC Configuration document functions reference + +## Synopsis + +Functions available within a configuration document for runtime processing. + +## Description + +DSC configuration documents support the use of functions that DSC processes at runtime to determine +values for the document. These functions enable you to define configurations that reuse values and +are easier to maintain. + +For DSC to recognize a function, it must be placed within square brackets in a string. DSC +configuration document functions use the following syntax: + +```Syntax +[(...)] +``` + +When using functions in YAML, you must specify the function with a string value that is wrapped in +double quotation marks or uses the [folded][01] or [literal][02] block syntax. When using the +folded or literal block syntaxes, always use the [block chomping indicator][03] (`-`) to trim +trailing line breaks and empty lines. + +```yaml +# Double quoted syntax +: "[(...)]" +# Folded block syntax +: >- + [(...)] +# Literal block syntax +: |- + [(...)] +``` + +You can nest functions, using the output of a nested function as a parameter value for an outer +function. DSC processes nested functions from the innermost function to outermost function. + +```Syntax +[(())] +``` + +It can be difficult to read long functions, especially when they're deeply nested. You can use +newlines to break long functions into a more readable format with the folded or literal block +syntax. + +```yaml +# Multi-line folded block syntax +: >- + [( + ( + () + ) + )] +# Multi-line literal block syntax +: |- + [( + ( + () + ) + )] +``` + +## Examples + +### Example 1 - Use a function with valid syntaxes + +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. + +```yaml +# overview.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +resources: + - name: Double quoted syntax + type: Test/Echo + properties: + text: "[base64('ab')]" + - name: Folded block syntax + type: Test/Echo + properties: + text: >- + [base64('ab')] + - name: Literal block syntax + type: Test/Echo + properties: + text: |- + [base64('ab')] +``` + +```sh +dsc --input-file overview.example.1.dsc.config.yaml config get +``` + +```yaml +results: +- name: Double quoted syntax + type: Test/Echo + result: + actualState: + text: YWI= +- name: Folded block syntax + type: Test/Echo + result: + actualState: + text: YWI= +- name: Literal block syntax + type: Test/Echo + result: + actualState: + text: YWI= +messages: [] +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`. + +```yaml +# overview.example.2.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +resources: + - name: Echo the concatenated strings 'a' and 'b' + type: Test/Echo + properties: + text: "[concat('a', 'b')]" +``` + +```sh +dsc --input-file overview.example.2.dsc.config.yaml config get +``` + +```yaml +results: +- name: Echo the concatenated strings 'a' and 'b' + type: Test/Echo + result: + actualState: + text: ab +messages: [] +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. +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 +resources: + - name: Echo the concatenated strings 'a' and 'b' as base64 + type: Test/Echo + properties: + text: "[base64(concat('a', 'b'))]" + - name: Echo the concatenated strings 'c' and 'd' as base64 + type: Test/Echo + properties: + text: "[base64(concat('c', 'd'))]" + - name: Echo the concatenated base64 of strings 'ab' and 'cd' + type: Test/Echo + properties: + text: "[concat(base64(concat('a', 'b')), base64(concat('c', 'd')))]" + - name: Echo the concatenated base64 of strings 'ab' and 'cd' as base64 + type: Test/Echo + properties: + # text: "[base64(concat(base64(concat('a', 'b')), base64(concat('c', 'd'))))]" + text: >- + [base64( + concat( + base64(concat('a', 'b')), + base64(concat('c', 'd')) + ) + )] +``` + +```sh +dsc --input-file overview.example.3.dsc.config.yaml config get +``` + +```yaml +results: +- name: Echo the concatenated strings 'a' and 'b' as base64 + type: Test/Echo + result: + actualState: + text: YWI= +- name: Echo the concatenated strings 'c' and 'd' as base64 + type: Test/Echo + result: + actualState: + text: Y2Q= +- name: Echo the concatenated base64 of strings 'ab' and 'cd' + type: Test/Echo + result: + actualState: + text: YWI=Y2Q= +- name: Echo the concatenated base64 of strings 'ab' and 'cd' as base64 + type: Test/Echo + result: + actualState: + text: WVdJPVkyUT0= +messages: [] +hadErrors: false +``` + +## Functions + +- [base64()][04] +- [concat()][05] +- [resourceId()][06] + +[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 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 new file mode 100644 index 0000000..3e16fa7 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/resourceId.md @@ -0,0 +1,111 @@ +--- +description: Reference for the 'resourceId' DSC configuration document function +ms.date: 01/17/2024 +ms.topic: reference +title: resourceId +--- + +# resourceId + +## Synopsis + +Returns the unique identifier of a resource. + +## Syntax + +```Syntax +resourceId('', '') +``` + +## Description + +The `resourceId()` function returns a handle to a specific resource instance in the configuration. +This function enables instances to reference another instance for the [dependsOn][01] option. + +> [!NOTE] +> When using the `resourceId` function for [nested resource instances][02], instances can only +> reference other instances in the same resource provider or group instance. They can't use the +> `resourceId()` function to lookup instances at the top-level of the configuration document or +> inside another provider or group instance. + +## Examples + +### Example 1 - Reference a resource as a dependency + +The following configuration uses the `resourceId()` function to reference the instance named +`Tailspin Key` as a dependency of the `Update Tailspin Automatically` resource instance. + +```yaml +# resourceId.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +resources: + - name: Tailspin Key + type: Microsoft.Windows/Registry + properties: + keyPath: HKCU\tailspin + _ensure: Present + - name: Update Tailspin Automatically + type: Microsoft.Windows/Registry + properties: + keyPath: HKCU\tailspin\updates + valueName: automatic + valueData: + String: enable + dependsOn: + - "[resourceId('Microsoft.Windows/Registry', 'Tailspin Key')]" +``` + +### Example 2 - Reference a group resource as a dependency + +The following configuration uses the `resourceId()` function to specify the `DSC/AssertionGroup` +resource instance named 'IsWindows' as a dependency of the `Example Key` resource instance. + +```yaml +# resourceId.example.2.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +resources: + - name: IsWindows + type: DSC/AssertionGroup + properties: + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + resources: + - name: os + type: Microsoft/OSInfo + properties: + family: Windows + - name: Example Key + type: Microsoft.Windows/Registry + properties: + keyPath: HKCU\example + _exist: true +``` + +## Parameters + +### resourceTypeName + +The value of the [type][03] property of the resource instance to reference. The value must be the +[fully qualified type name][04] for the resource. + +```yaml +Type: string +Required: true +Position: 0 +``` + +### instanceName + +The value of the [name][05] property of the resource instance to reference. + +```yaml +Type: string +Required: true +Position: 0 +``` + + +[01]: ../resource.md#dependson +[02]: /powershell/dsc/glossary#nested-resource-instance +[03]: ../resource.md#type +[04]: ../../definitions/resourceType.md +[05]: ../resource.md#name 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 9251479..50f78f0 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: 08/04/2023 +ms.date: 01/17/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/08/config/document.parameter.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.parameter.json Type: object ``` 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 bc95e99..cf01020 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: 09/06/2023 +ms.date: 01/17/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/08/config/document.resource.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.resource.json Type: object ``` @@ -72,7 +72,7 @@ The `properties` of a resource instance define its desired state. The value of t be an object. For assertion resources, the value may be an empty object (`{}`). DSC uses the DSC Resource's instance schema to validate the defined properties. - + ```yaml Type: object @@ -85,9 +85,10 @@ To declare that a resource instance is dependent on another instance in the conf the `dependsOn` property. This property defines a list of DSC Resource instances that DSC must successfully process before -processing this instance. Each value for this property must be the `resourceID()` lookup for -another instance in the configuration. Multiple instances can depend on the same instance, but -every dependency for an instance must be unique in that instance's `dependsOn` property. +processing this instance. Each value for this property must be the [resourceID() function][02] +lookup for another instance in the configuration. Multiple instances can depend on the same +instance, but every dependency for an instance must be unique in that instance's `dependsOn` +property. The `resourceID()` function uses this syntax: @@ -120,7 +121,7 @@ resource named `Tailspin Key`: ``` > [!NOTE] -> When defining dependencies for [nested resource instances][02], instances can only reference +> When defining dependencies for [nested resource instances][03], instances can only reference > dependencies in the same resource provider or group instance. They can't use the `resourceId()` > function to lookup instances at the top-level of the configuration document or inside another > provider or group instance. @@ -128,7 +129,11 @@ resource named `Tailspin Key`: > If a top-level instance depends on a nested instance, use the `resourceId()` function to lookup > the instance of the provider or group containing the dependency instance instead. - +For more information about using functions in configuration documents, see +[DSC Configuration document functions reference][04]. For more information about the `resourceId()` +function, see [resourceId][02]. + + ```yaml Type: array @@ -139,7 +144,8 @@ ItemsPattern: ^\[resourceId\(\s*'\w+(\.\w+){0,2}\/\w+'\s*,\s*'[a-zA-Z0-9 ]+ ``` [01]: ../definitions/resourceType.md -[02]: /powershell/dsc/glossary#nested-resource-instance - - - +[02]: functions/resourceId.md +[03]: /powershell/dsc/glossary#nested-resource-instance +[04]: functions/overview.md + + 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 721bffb..77c3847 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: 08/04/2023 +ms.date: 01/17/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/08/definitions/message.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/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 347a1e2..6654bd8 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: 08/04/2023 +ms.date: 01/17/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/08/definitions/parameters/dataTypes.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/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/resourceType.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceType.md index 5f0ffec..bb285bd 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: 08/04/2023 +ms.date: 01/17/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/08/definitions/resourceType.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/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 9d080e2..f605cb0 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: 08/04/2023 +ms.date: 01/17/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/08/outputs/config/get.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/config/get.json Type: object ``` 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 8795e41..81b9eff 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: 08/04/2023 +ms.date: 01/17/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/08/outputs/config/set.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/config/set.json Type: object ``` 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 b9a3d86..0faa28e 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: 08/04/2023 +ms.date: 01/17/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/08/outputs/config/test.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/config/test.json Type: object ``` 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 fa964e3..552d49b 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: 08/04/2023 +ms.date: 01/17/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/08/outputs/resource/get.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json Type: object ``` 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 a7365e5..984b993 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: 08/04/2023 +ms.date: 01/17/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/08/outputs/resource/list.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/list.json Type: object ``` 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 4033ad8..c7ab0cf 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: 08/04/2023 +ms.date: 01/17/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/08/outputs/resource/set.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json Type: object ``` 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 818f27a..4df6739 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: 08/04/2023 +ms.date: 01/17/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/08/outputs/resource/test.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json Type: object ``` 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 91f52c5..004e65e 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: 09/06/2023 +ms.date: 01/17/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/08/resource/manifest.export.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.export.json Type: object ``` 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 2b2d97f..857b41b 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: 09/27/2023 +ms.date: 01/17/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/08/resource/manifest.get.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.get.json Type: object ``` 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 index 79935d0..e3134e4 100644 --- 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 @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'provider' property in a DSC Resource manifest -ms.date: 08/04/2023 +ms.date: 01/17/2024 ms.topic: reference title: DSC Resource manifest provider property schema reference --- @@ -15,7 +15,7 @@ Defines a DSC Resource as a DSC Resource Provider. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.provider.json Type: object ``` 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 89df918..95c5c16 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: 09/27/2023 +ms.date: 01/17/2024 ms.topic: reference title: Command-based DSC Resource manifest schema reference --- @@ -15,7 +15,7 @@ The JSON file that defines a command-based DSC Resource. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json Type: object ``` @@ -46,12 +46,42 @@ The `$schema` property indicates the canonical URI of this schema that the manif against. This property is mandatory. DSC uses this value to validate the manifest against the correct JSON schema. +For every version of the schema, there are three valid urls: + +- `.../resource/manifest.json` + + The URL to the canonical non-bundled schema. When it's used for validation, the validating client + needs to retrieve this schema and every schema it references. + +- `.../bundled/resource/manifest.json` + + The URL to the bundled schema. When it's used for validation, the validating client only needs to + retrieve this schema. + + This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can still + validate the document when it uses this schema, other tools may error or behave in unexpected + ways. + +- `.../bundled/resource/manifest.vscode.json` + + The URL to the enhanced authoring schema. This schema is much larger than the other schemas, as + it includes additional definitions that provide contextual help and snippets that the others + don't include. + + This schema uses keywords that are only recognized by VS Code. While DSC can still validate the + document when it uses this schema, other tools may error or behave in unexpected ways. + ```yaml Type: string Required: true Format: URI ValidValues: [ + 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 + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json ] ``` 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 f91435f..48d03d1 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: 08/04/2023 +ms.date: 01/17/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/08/resource/manifest.schema.json#/properties/embedded +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.schema.json#/properties/embedded Type: object ``` @@ -91,24 +91,23 @@ processing. The well-known properties always start with an underscore (`_`) and use these properties may not override or extend them. If a resource specifies a well-known property in the embedded schema, the schema _must_ define the property as a reference. -- [_ensure](#_ensure) +- [_exist](#_exist) - [_inDesiredState](#_indesiredstate) - [_purge](#_purge) - [_rebootRequested](#_rebootrequested) -#### _ensure +#### _exist -The `_ensure` property indicates that the resource can enforce whether instances exist using the -shared present and absent semantics. If a resource must distinguish between states beyond whether -an instance is present or absent, the resource should define its own `ensure` property without the -leading underscore. This property provides shared semantics for DSC Resources and integrating -tools, but doesn't enable any additional built-in processing with DSC. +The `_exist` property indicates that the resource can enforce whether instances exist, handling +whether an instance should be added, updated, or removed during a set operation. This property +provides shared semantics for DSC Resources and integrating tools, but doesn't enable any +additional built-in processing with DSC. If defined, this property must be a reference to the schema for the well-known property: ```json -"_ensure": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" +"_exist": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/exist.json" } ``` @@ -124,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/08/resource/properties/inDesiredState.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/inDesiredState.json" } ``` @@ -140,7 +139,7 @@ If defined, this property must be a reference to the schema for the well-known p ```json "_inDesiredState": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/purge.json" } ``` @@ -156,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/08/resource/properties/rebootRequested.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/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 e37db19..3bcbbd8 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: 08/04/2023 +ms.date: 01/17/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/08/resource/manifest.schema.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/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 3773a66..6977734 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: 09/27/2023 +ms.date: 01/17/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/08/resource/manifest.set.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.set.json Type: object ``` 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 aac8a97..e2f7dc9 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: 09/27/2023 +ms.date: 01/17/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/08/resource/manifest.test.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.test.json Type: object ``` 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 89b13df..c182470 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: 08/04/2023 +ms.date: 01/17/2024 ms.topic: reference title: DSC Resource manifest validate property schema reference --- @@ -15,7 +15,7 @@ This property ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.validate.json Type: object ``` diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/ensure.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/ensure.md index 0bb6045..97085e7 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/ensure.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/ensure.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_ensure' well-known DSC Resource property. -ms.date: 08/04/2023 +ms.date: 01/17/2024 ms.topic: reference title: DSC Resource _ensure property schema --- @@ -22,6 +22,11 @@ ValidValues: [Absent, Present] ## Description +> [!IMPORTANT] +> Starting with DSC v3.0.0-alpha.4 and schema version `2023/10` this well-known property is removed +> from the schema. It's replaced by the [_exist][01] property. Microsoft recommends migrating +> resources to use the `_exist` keyword instead. + The `_ensure` property indicates that the resource can enforce whether instances exist using the shared present and absent semantics. @@ -54,3 +59,5 @@ specifically a file, or exists as a symlink. In that case, the resource would de "default": "present" } ``` + +[01]: exist.md 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 new file mode 100644 index 0000000..4e75c8b --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md @@ -0,0 +1,49 @@ +--- +description: JSON schema reference for the '_exist' well-known DSC Resource property. +ms.date: 10/05/2023 +ms.topic: reference +title: DSC Resource _exist property schema +--- + +# DSC Resource _exist property schema + +## Synopsis + +Indicates whether an instance should exist. + +## Metadata + +```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 +Type: boolean +DefaultValue: true +``` + +## Description + +The `_exist` property indicates that the resource can enforce whether instances exist, handling +whether an instance should be added, updated, or removed during a set operation. This property +provides shared semantics for DSC Resources and integrating tools, but doesn't enable any +additional built-in processing with DSC. + +Resources should only define this property when their implementation adheres to the following +behavior contract: + +1. When the desired state for `_exist` is `true`, the resource expects the instance to exist. If it + doesn't exist, the resource creates or adds the instance during the set operation. +1. When the desired state for `_exist` is `false`, the resource expects the instance to not exist. + If it does exist, the resource deletes or removes the instance during the set operation. +1. When the get operation queries for an instance that doesn't exist, the returned JSON always + defines the `_exist` property as `false`. + + The resource _may_ omit the `_exist` property from the result JSON when the instance exists. + +To add this property to a resource's instance schema, define the property with the following +snippet: + +```json +"_exist": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/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 947506b..a32f29d 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: 08/04/2023 +ms.date: 01/17/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/08/resource/properties/inDesiredState.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/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/08/resource/properties/inDesiredState.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/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 2ceb750..2c02322 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: 08/04/2023 +ms.date: 01/17/2024 ms.topic: reference title: DSC well-known properties --- @@ -13,15 +13,14 @@ DSC has support for several well-known properties. Some well-known properties en to use built-in processing. The well-known properties always start with an underscore (`_`) and DSC Resources that use these properties may not override or extend them. -## _ensure +## _exist -The `_ensure` property indicates that the resource can enforce whether instances exist using the -shared present and absent semantics. If a resource must distinguish between states beyond whether -an instance is present or absent, the resource should define its own `ensure` property without the -leading underscore. This property provides shared semantics for DSC Resources and integrating -tools, but doesn't enable any additional built-in processing with DSC. +The `_exist` property indicates that the resource can enforce whether instances exist, handling +whether an instance should be added, updated, or removed during a set operation. This property +provides shared semantics for DSC Resources and integrating tools, but doesn't enable any +additional built-in processing with DSC. -For more information, see [DSC Resource _ensure property schema][01]. +For more information, see [DSC Resource _exist property schema][01]. ## _inDesiredState @@ -48,7 +47,7 @@ this property in their manifest. For more information, see [DSC Resource _rebootRequested property schema][06]. -[01]: ensure.md +[01]: exist.md [02]: ../manifest/test.md [03]: ../manifest/root.md [04]: inDesiredState.md 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 9d92f35..1624979 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: 08/04/2023 +ms.date: 01/17/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/08/resource/properties/purge.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/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/08/resource/properties/purge.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/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 dfbe92a..fd6f139 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: 08/04/2023 +ms.date: 01/17/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/08/resource/properties/rebootRequested.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/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/08/resource/properties/rebootRequested.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/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 07f85e2..e4766f9 100644 --- a/dsc/docs-conceptual/dsc-3.0/toc.yml +++ b/dsc/docs-conceptual/dsc-3.0/toc.yml @@ -47,6 +47,8 @@ items: items: - name: dsc command href: reference/cli/dsc.md + - name: dsc completer command + href: reference/cli/completer/command.md - name: dsc config command items: - name: dsc config @@ -87,6 +89,16 @@ items: href: reference/schemas/config/parameter.md - name: Resource Instances href: reference/schemas/config/resource.md + - name: Functions + items: + - name: Overview + href: reference/schemas/config/functions/overview.md + - name: base64 + href: reference/schemas/config/functions/base64.md + - name: concat + href: reference/schemas/config/functions/concat.md + - name: resourceId + href: reference/schemas/config/functions/resourceId.md - name: Resource items: - name: Manifests @@ -117,6 +129,8 @@ items: href: reference/schemas/resource/properties/overview.md - name: _ensure href: reference/schemas/resource/properties/ensure.md + - name: _exist + href: reference/schemas/resource/properties/exist.md - name: _inDesiredState href: reference/schemas/resource/properties/inDesiredState.md - name: _purge @@ -143,6 +157,14 @@ items: href: reference/schemas/outputs/resource/set.md - name: dsc resource test output href: reference/schemas/outputs/resource/test.md + - name: Shared definitions + items: + - name: message + href: reference/schemas/definitions/message.md + - name: resourceType + href: reference/schemas/definitions/resourceType.md + - name: Parameter dataTypes + href: reference/schemas/definitions/parameters/dataTypes.md - name: Resource reference items: - name: Command-based resources