diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b01251b..94b24f1d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ title: "Desired State Configuration changelog" description: >- A log of the changes for releases of DSCv3. -ms.date: 09/06/2023 +ms.date: 09/27/2023 --- # Changelog @@ -20,10 +20,74 @@ 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.2...main +[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.3...main +## [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 +in this release, see the [diff on GitHub][compare-v3.0.0-alpha.3]. + + +[release-v3.0.0-alpha.3]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-alpha.3 "Link to the DSC v3.0.0-alpha.3 release on GitHub" +[compare-v3.0.0-alpha.3]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.2...v3.0.0-alpha.3 + +### Changed + +- Replaced the `manifestVersion` property for resource manifests with [$schema][15]. Instead of + specifying a semantic version, resources need to indicate which canonical schema DSC should use + to validate and process the manifest. + +
Related work items + + - Issues: [#127][#127] + - PRs: [#199][#199] + +
+ +- Updated the `preTest` property for the `set` command in resource manifests to + [implementsPretest][16] to more make the manifest easier to read and understand. + +
Related work items + + - PRs: [#197][#197] + +
+ +- The [dsc resource set][17] 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. + +
Related work items + + - Issues: [#98][#98] + - PRs: [#197][#197] + +
+ +- 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. + + 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. + +
Related work items + + - PRs: [#198][#198] + +
+ +- The `input` property for the [get][18] 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. + +
Related work items + + - PRs: [#198][#198] + +
+ ## [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 @@ -219,19 +283,32 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [13]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource?view=dsc-3.0&preserve-view=true [14]: docs/reference/schemas/config/document.md#schema + +[15]: docs/reference/schemas/resource/manifest/root.md#schema +[16]: docs/reference/schemas/resource/manifest/set.md#implementspretest +[17]: docs/reference/cli/resource/set.md +[18]: docs/reference/schemas/resource/manifest/get.md#input +[19]: docs/reference/schemas/resource/manifest/set.md#input +[20]: docs/reference/schemas/resource/manifest/test.md#input + -[#163]: https://github.com/PowerShell/DSC/163 -[#156]: https://github.com/PowerShell/DSC/156 -[#168]: https://github.com/PowerShell/DSC/168 -[#172]: https://github.com/PowerShell/DSC/172 -[#182]: https://github.com/PowerShell/DSC/182 -[#181]: https://github.com/PowerShell/DSC/181 -[#177]: https://github.com/PowerShell/DSC/177 -[#150]: https://github.com/PowerShell/DSC/150 -[#176]: https://github.com/PowerShell/DSC/176 -[#133]: https://github.com/PowerShell/DSC/133 -[#73]: https://github.com/PowerShell/DSC/73 -[#174]: https://github.com/PowerShell/DSC/174 -[#171]: https://github.com/PowerShell/DSC/171 -[#45]: https://github.com/PowerShell/DSC/45 -[#175]: https://github.com/PowerShell/DSC/175 +[#127]: https://github.com/PowerShell/DSC/issues/127 +[#133]: https://github.com/PowerShell/DSC/issues/133 +[#150]: https://github.com/PowerShell/DSC/issues/150 +[#156]: https://github.com/PowerShell/DSC/issues/156 +[#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 +[#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 +[#197]: https://github.com/PowerShell/DSC/issues/197 +[#198]: https://github.com/PowerShell/DSC/issues/198 +[#199]: https://github.com/PowerShell/DSC/issues/199 +[#45]: https://github.com/PowerShell/DSC/issues/45 +[#73]: https://github.com/PowerShell/DSC/issues/73 +[#98]: https://github.com/PowerShell/DSC/issues/98 diff --git a/docs/reference/cli/resource/set.md b/docs/reference/cli/resource/set.md index 490dbc8c..691a7e2b 100644 --- a/docs/reference/cli/resource/set.md +++ b/docs/reference/cli/resource/set.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource set' command -ms.date: 08/04/2023 +ms.date: 09/27/2023 ms.topic: reference title: dsc resource set --- @@ -31,17 +31,31 @@ This subcommand can only be invoked for command-based DSC Resources that define of their resource manifest. If this subcommand is called for a resource that doesn't define a set operation, DSC raises an error. -The subcommand's behavior depends on the value of the `set.preTest` option in the resource -manifest: - -- If the resource's manifest doesn't define the `set.preTest` key as `true`, DSC invokes the - resource's test operation to determine whether a set operation is required. - - If the instance is already in the desired state, DSC doesn't invoke the set operation. If the - instance isn't in the desired state, DSC invokes the resource's set operation with the desired - state as input. -- If the resource's manifest defines the `set.preTest` key as `true`, DSC invokes the resource's - set operation without testing the resource state first. +> [!IMPORTANT] +> The `dsc resource set` command always invokes the `set` operation for the resource. Resources +> may, but aren't required to, implement logic that pretests an instance for the `set` operation. +> +> This is different from how [dsc config set][02] works, where DSC always tests an instance, either +> synthetically or by invoking the `test` operation for the resource, and only invokes `set` for an +> instance if it's not in the desired state. +> +> Command-based resources indicate whether they implement pretest for the `set` operation by +> defining the [set.implementsPretest][03] property in their resource manifest. If that property is +> defined as `true`, it indicates that the resource implements pretest. If `set.implementsPretest` +> is set to `false` or is undefined, the manifest indicates that the resource doesn't implement +> pretest. +> +> If a resource indicates that it implements pretest, users should expect that the resource only +> modifies an instance during a `set` operation if the pretest shows that the instance isn't in the +> desired state. +> +> If a resource doesn't implement pretest, users should expect that the resource always modifies an +> instance during a `set` operation. +> +> For resources that don't implement pretest for the `set` operation, Microsoft recommends always +> calling `dsc resource test` against an instance to see whether it's in the desired state _before_ +> invoking `dsc resource set`. This can help avoid accidental errors caused by resources that don't +> implement a fully idempotent `set` command. ## Examples @@ -115,7 +129,9 @@ Mandatory: false This command returns JSON output that includes the actual state of the instance before and after the set operation, and the list of properties that the set operation modified. For more -information, see [dsc resource set result schema][02]. +information, see [dsc resource set result schema][04]. [01]: ../config/set.md -[02]: ../../schemas/outputs/resource/set.md +[02]: ../config/set.md +[03]: ../../schemas/resource/manifest/set.md#implementspretest +[04]: ../../schemas/outputs/resource/set.md diff --git a/docs/reference/schemas/resource/manifest/get.md b/docs/reference/schemas/resource/manifest/get.md index bc186f6c..2b2d97fc 100644 --- a/docs/reference/schemas/resource/manifest/get.md +++ b/docs/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: 08/04/2023 +ms.date: 09/27/2023 ms.topic: reference title: DSC Resource manifest get property schema reference --- @@ -24,6 +24,12 @@ 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. + ## Examples ### Example 1 - Minimal definition @@ -104,16 +110,36 @@ Default: [] ### input -The `input` property defines how to pass input to the resource. The value of this property must -be one of the following strings: +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 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"`. -- `args` - Indicates that the resource expects the properties of an instance to be specified with - command line arguments. This option isn't implemented yet. + 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 -Default: stdin -ValidValues: [args, stdin] +ValidValues: [env, stdin] ``` diff --git a/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md index 3ac20293..1bfa3817 100644 --- a/docs/reference/schemas/resource/manifest/root.md +++ b/docs/reference/schemas/resource/manifest/root.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a DSC Resource manifest -ms.date: 08/04/2023 +ms.date: 09/27/2023 ms.topic: reference title: Command-based DSC Resource manifest schema reference --- @@ -33,24 +33,26 @@ The rest of this document describes the manifest's schema. The manifest must include these properties: -- [manifestVersion](#manifestversion) +- [$schema](#schema) - [type](#type) - [version](#version) - [get](#get) ## Properties -### manifestVersion +### $schema -The `manifestVersion` property indicates the semantic version (semver) of this schema that the -manifest validates against. This property is mandatory. DSC uses this value to validate the -manifest against the correct JSON schema. +The `$schema` property indicates the canonical URI of this schema that the manifest validates +against. This property is mandatory. DSC uses this value to validate the manifest against the +correct JSON schema. ```yaml Type: string 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-]+)*))?$ -ValidValues: ['1.0'] +Format: URI +ValidValues: [ + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json + ] ``` ### type @@ -144,8 +146,8 @@ defined, the DSC can't manage instances of the resource. It can only get their c 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`, `preTest`, and `returns` properties are -optional. For more information, see [DSC Resource manifest set property schema reference][08]. +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]. ```yaml Type: object diff --git a/docs/reference/schemas/resource/manifest/set.md b/docs/reference/schemas/resource/manifest/set.md index e286e582..3773a666 100644 --- a/docs/reference/schemas/resource/manifest/set.md +++ b/docs/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: 08/04/2023 +ms.date: 09/27/2023 ms.topic: reference title: DSC Resource manifest set property schema reference --- @@ -40,9 +40,9 @@ This example is from the `Microsoft.Windows/Registry` DSC Resource. "config", "set" ], - "input": "stdin", - "preTest": true, - "return": "state" + "input": "stdin", + "implementsPretest": true, + "return": "state" } ``` @@ -59,9 +59,9 @@ running: { ... } | registry config set ``` -Because the manifest defines `preTest` as `true`, DSC won't call the `test` method for the resource -before calling `set`. This setting indicates that the resource itself tests instances before -enforcing their desired state. +Because the manifest defines `implementsPretest` as `true`, DSC won't call the `test` method for +the resource before calling `set`. This setting indicates that the resource itself tests instances +before enforcing their desired state. The manifest defines `return` as `state`, indicating that it only returns the final state of the resource after the `set` method runs. DSC compares the desired state to the return data of this @@ -100,27 +100,51 @@ Default: [] ### input -The `input` property defines how to pass input to the resource. The value of this property must -be one of the following strings: +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. -- `args` - Indicates that the resource expects the properties of an instance to be specified - with command line arguments. This option isn't implemented yet. -- `stdin` - Indicates that the resource expects a JSON blob representing an instance from - `stdin`. +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 -Default: stdin -ValidValues: [args, stdin] +ValidValues: [env, stdin] ``` -### preTest +### implementsPretest + +The `implementsPretest` property defines whether the resource tests whether the instance is in the +desired state internally before enforcing the desired state. Set this property to `true` when the +resource tests the instance as part of the `set` operation. Set this property to `false` when it +doesn't. + +When this value is `false`, it indicates that users should always call `dsc resource test` against +the instance before invoking the `dsc resource set` command against the resource. -The `preTest` property defines whether the resource tests the instance internally before -enforcing the desired state. Set this property to `true` when the resource tests the instance. -Set this property to `false` to ensure DSC tests the instance first instead. The default value -is `false`. +The default value is `false`. ```yaml Type: boolean diff --git a/docs/reference/schemas/resource/manifest/test.md b/docs/reference/schemas/resource/manifest/test.md index 2c71aa59..aac8a973 100644 --- a/docs/reference/schemas/resource/manifest/test.md +++ b/docs/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: 08/04/2023 +ms.date: 09/27/2023 ms.topic: reference title: DSC Resource manifest test property schema reference --- @@ -108,19 +108,38 @@ Default: [] ### input -The `input` property defines how to pass input to the resource. The value of this property must -be one of the following strings: +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 `test` operation. -- `args` - Indicates that the resource expects the properties of an instance to be specified - with command line arguments. This option isn't implemented yet. -- `stdin` - Indicates that the resource expects a JSON blob representing an instance from - `stdin`. +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 -Default: stdin -ValidValues: [args, stdin] +ValidValues: [env, stdin] ``` ### return