diff --git a/dsc/docs-conceptual/dsc-3.0/changelog.md b/dsc/docs-conceptual/dsc-3.0/changelog.md index 8dcca0d..b695665 100644 --- a/dsc/docs-conceptual/dsc-3.0/changelog.md +++ b/dsc/docs-conceptual/dsc-3.0/changelog.md @@ -3,7 +3,7 @@ title: "Desired State Configuration changelog" description: >- A log of the changes for releases of DSCv3. ms.topic: whats-new -ms.date: 05/09/2024 +ms.date: 06/24/2024 --- # Changelog @@ -46,7 +46,7 @@ This section includes a summary of user-facing changes since the last release. F changes since the last release, see the [diff on GitHub][unreleased]. -[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-preview.7...main +[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-preview.8...main +## [v3.0.0-preview.8][release-v3.0.0-preview.8] - 2024-06-19 + +This section includes a summary of changes for the `preview.8` release. For the full list of changes +in this release, see the [diff on GitHub][compare-v3.0.0-preview.8]. + + +[release-v3.0.0-preview.8]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-preview.8 "Link to the DSC v3.0.0-preview.8 release on GitHub" +[compare-v3.0.0-preview.8]: https://github.com/PowerShell/DSC/compare/v3.0.0-preview.7...v3.0.0-preview.8 + +### Changed + +- Changed the `Microsoft.DSC/PowerShell` adapter to only handle PowerShell DSC Resources + implemented as classes. The `Microsoft.Windows/WindowsPowerShell` adapter continues to work with + classic PSDSC resources. Neither adapter supports composite PSDSC resources. This change + simplified the code and coincided with ensuring that the `Microsoft.DSC/PowerShell` adapter works + correctly on Linux and macOS as well as Windows. This change also brought performance + improvements to the adapter, speeding up resource invocation and discovery. + +
Related work items + + - Issues: _None_. + - PRs: + - [#435][#435] + - [#439][#439] + +
+ +### Added + +- Added the [`--what-if` (`-w`)][p8-01] option to the [dsc config set][cmd-cset] command. When you + call `dsc config set` with the `--what-if` option, DSC doesn't actually invoke the resources to + enforce the desired state. Instead, it returns the expected output for the command, showing the + before and after state for each resource instance. + + The output for the `dsc config set` operation with the `--what-if` operation is the same as an + [actual configuration set operation][p8-02], except that the metadata field + [executionType][p8-03] is set to `WhatIf` instead of `Actual`. + + By default, the generated output is synthetic, based on the results of the resources' `test` + operation. Resources can define the [whatIf][p8-04] property in their resource manifest to + participate in what-if operations, reporting more specifically how they will change the system. + For example, participating resources could indicate whether an actual set operation will require + a reboot or whether the current user has the correct permissions to manage that resource + instance. + + Participating resources have the [WhatIf capability][p8-05]. + +
Related work items + + - Issues: [#70][#70] + - PRs: + - [#400][#400] + - [#441][#441] + +
+ +- Added support for [importer resources][p8-06]. These resources resolve external sources to a + nested DSC Configuration document. The resolved instances are processed as nested resource + instances. + + This required some updates to the schemas, all backwards-compatible: + + - Added a new [resourceKind][p8-07] named `Import`. + - Added the [resolve][p8-08] command to resource manifests. + - Added the new [`Resolve`][p8-09] capability, returned in the output for the + [dsc resource list][cmd-rlist] command when DSC discovers an importer resource. + +
Related work items + + - Issues: [#429][#429] + - PRs: + - [#412][#412] + - [#464][#464] + +
+ +- Added the `Microsoft.DSC/Include` importer resource to resolve instances from an external + configuration document. The resolved instances are processed as nested instances for the + `Microsoft.DSC/Include` resource instance. + + You can use this resource to write smaller configuration documents and compose them as needed. + For example, you could define a security baseline and a web server configuration separately, then + combine them for a given application: + + ```yaml + $schema: &schema https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json + resources: + # Group of included baseline configurations + - name: Baselines + type: Microsoft.DSC/Group + properties: + $schema: *schema + resources: + - name: Security Baseline + type: Microsoft.DSC/Include + properties: + configurationFile: security_baseline.dsc.yaml + parametersFile: security_baseline.parameters.yaml + - name: Web Server Baseline + type: Microsoft.DSC/Include + properties: + configurationFile: web_baseline.dsc.yaml + parametersFile: web_baseline.parameters.yaml + dependsOn: + - "[resourceId('Microsoft.DSC/Include', 'Security Baseline')]" + + # application configuration instances, all depend on the baselines + - name: Application configuration + type: MyApp/Settings + properties: + someSetting: someValue + dependsOn: + - "[resourceId('Microsoft.DSC/Group', 'Baselines')]" + ``` + +
Related work items + + - Issues: [#429][#429] + - PRs: [#412][#412] + +
+ +- Added caching for PowerShell Desired State Configuration (PSDSC) resources when using the + `Microsoft.DSC/PowerShell` and `Microsoft.Windows/PowerShell` adapters. The adapters use the + cache to speed up resource discovery. The performance improvement reduced the resource list time + under tests from eight seconds to two seconds, and reduced invocation operation times by half. + + The adapters cache the resources in the following locations, depending on your platform: + + | Adapter | Platform | Path | + | :----------------------------: | :------: | :---------------------------------------------- | + | `Microsoft.DSC/PowerShell` | Linux | `$HOME/.dsc/PSAdapterCache.json` | + | `Microsoft.DSC/PowerShell` | macOS | `$HOME/.dsc/PSAdapterCache.json` | + | `Microsoft.DSC/PowerShell` | Windows | `%LOCALAPPDATA%\dsc\PSAdapterCache.json` | + | `Microsoft.Windows/PowerShell` | Windows | `%LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json` | + + The adapters check whether the cache is stale on each run and refresh it if: + + - The `PSModulePath` environmental variable is updated. + - Any module is added or removed from the `PSModulePath`. + - Any related files in a cached PSDSC resource module has been updated since the cache was + written. The adapter watches the `LastWriteTime` of module files with the following extensions: + `.ps1`, `.psd1`, `.psm1`, and `.mof`. + +
Related work items + + - Issues: [#371][#371] + - PRs: [#432][#432] + +
+ +- Added the `DSC.PackageManagement/Apt` resource for managing software on systems that use the + advanced package tool (APT). In this release, you can use the resource to: + + - Install the latest version of a package. + - Uninstall a package. + - Get the current state of a package. + - Export every installed package as a DSC resource instance. + +
Related work items + + - Issues: _None_. + - PRs: [#434][#434] + +
+ +- Added the `Microsoft.DSC.Experimental/SystemctlService` class-based PSDSC resource. It has the + `Get` and `Export` [capabilities][p8-10]. You can use it on Linux systems that manage services + with SystemD and `systemctl`. In this release, it doesn't support setting services. + +
Related work items + + - Issues: _None_. + - PRs: [#454][#454] + +
+ +### Fixed + +- Fixed the JSON Schema for [exit codes][p8-11] in the resource manifest to support negative + integers. Prior to this release, the DSC engine supported negative exit codes but the JSON Schema + forbid them. + +
Related work items + + - Issues: [#407][#407] + - PRs: [#410][#410] + +
+ +- Fixed the behavior of the [int()][int()] configuration function to error when given an input + value other than a string or integer. Prior to this release, when you specified a number with + a fractional part as input for the function, it coerced the input value to an integer representing + the fractional part. Starting with this release, the `int()` function raises an invalid input + error when the input value isn't a string or an integer. + +
Related work items + + - Issues: [#390][#390] + - PRs: [#438][#438] + +
+ +- Fixed the implementation to retrieve non-zero exit code descriptions for resource errors from the + resource manifest, if defined. Prior to this release, these error descriptions weren't surfaced. + +
Related work items + + - Issues: [#431][#431] + - PRs: [#444][#444] + +
+ + +[p8-01]: reference/cli/config/set.md#-w---what-if +[p8-02]: reference/schemas/outputs/config/set.md +[p8-03]: reference/schemas/metadata/Microsoft.DSC/properties.md#executiontype +[p8-04]: reference/schemas/resource/manifest/whatif.md +[p8-05]: reference/schemas/outputs/resource/list.md#capability-whatif +[p8-06]: reference/schemas/definitions/resourceKind.md#importer-resources +[p8-07]: reference/schemas/definitions/resourceKind.md +[p8-08]: reference/schemas/resource/manifest/resolve.md +[p8-09]: reference/schemas/outputs/resource/list.md#capability-resolve +[p8-10]: reference/schemas/outputs/resource/list.md#capabilities +[p8-11]: reference/schemas/resource/manifest/root.md#exitcodes + ## [v3.0.0-preview.7][release-v3.0.0-preview.7] - 2024-04-22 This section includes a summary of changes for the `preview.7` release. For the full list of changes @@ -127,7 +353,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-preview.7]. -- In this release, the term `DSC Resource Provider` is +- In this release, the term `DSC Resource Provider` is replaced with the more semantically accurate `DSC Resource Adapter`. These resources enable users to leverage resources that don't define a DSC Resource Manifest with DSC, like PSDSC resources - they're _adapters_ between DSCv3 and resources defined in a different way. @@ -1319,6 +1545,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#362]: https://github.com/PowerShell/DSC/issues/362 [#364]: https://github.com/PowerShell/DSC/issues/364 [#368]: https://github.com/PowerShell/DSC/issues/368 +[#371]: https://github.com/PowerShell/DSC/issues/371 [#373]: https://github.com/PowerShell/DSC/issues/373 [#375]: https://github.com/PowerShell/DSC/issues/375 [#376]: https://github.com/PowerShell/DSC/issues/376 @@ -1327,12 +1554,29 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#382]: https://github.com/PowerShell/DSC/issues/382 [#385]: https://github.com/PowerShell/DSC/issues/385 [#388]: https://github.com/PowerShell/DSC/issues/388 +[#390]: https://github.com/PowerShell/DSC/issues/390 [#397]: https://github.com/PowerShell/DSC/issues/397 +[#400]: https://github.com/PowerShell/DSC/issues/400 [#401]: https://github.com/PowerShell/DSC/issues/401 [#405]: https://github.com/PowerShell/DSC/issues/405 +[#407]: https://github.com/PowerShell/DSC/issues/407 +[#410]: https://github.com/PowerShell/DSC/issues/410 +[#412]: https://github.com/PowerShell/DSC/issues/412 +[#429]: https://github.com/PowerShell/DSC/issues/429 +[#431]: https://github.com/PowerShell/DSC/issues/431 +[#432]: https://github.com/PowerShell/DSC/issues/432 +[#434]: https://github.com/PowerShell/DSC/issues/434 +[#435]: https://github.com/PowerShell/DSC/issues/435 +[#438]: https://github.com/PowerShell/DSC/issues/438 +[#439]: https://github.com/PowerShell/DSC/issues/439 +[#441]: https://github.com/PowerShell/DSC/issues/441 +[#444]: https://github.com/PowerShell/DSC/issues/444 +[#454]: https://github.com/PowerShell/DSC/issues/454 +[#464]: https://github.com/PowerShell/DSC/issues/464 [#45]: https://github.com/PowerShell/DSC/issues/45 [#49]: https://github.com/PowerShell/DSC/issues/49 [#57]: https://github.com/PowerShell/DSC/issues/57 +[#70]: https://github.com/PowerShell/DSC/issues/70 [#73]: https://github.com/PowerShell/DSC/issues/73 [#75]: https://github.com/PowerShell/DSC/issues/75 [#89]: https://github.com/PowerShell/DSC/issues/89 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 06f18dd..ee78b0e 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: 05/09/2024 +ms.date: 06/24/2024 ms.topic: reference title: dsc config get --- @@ -52,7 +52,7 @@ document saved as `example.dsc.config.yaml`. $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Windows only - type: DSC/AssertionGroup + type: Microsoft.DSC/Assertion properties: $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: @@ -64,9 +64,9 @@ resources: type: Microsoft.Windows/Registry properties: keyPath: HKCU\example - _ensure: Present + _exist: true dependsOn: - - '[DSC/Assertion]Windows only' + - "[resourceId('Microsoft.DSC/Assertion', 'Windows only')" ``` ```sh 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 af63c1c..307137e 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: 05/09/2024 +ms.date: 06/24/2024 ms.topic: reference title: dsc config set --- @@ -53,7 +53,7 @@ The command inspects the resource instances defined in the configuration documen $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Windows only - type: DSC/AssertionGroup + type: Microsoft.DSC/Assertion properties: $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: @@ -65,9 +65,9 @@ resources: type: Microsoft.Windows/Registry properties: keyPath: HKCU\example - _ensure: Present + _exist: true dependsOn: - - '[DSC/Assertion]Windows only' + - "[resourceId('Microsoft.DSC/Assertion', 'Windows only')" ``` ```sh @@ -125,6 +125,20 @@ Type: String Mandatory: false ``` +### -w, --what-if + +When you specify this flag option, DSC doesn't actually change the system state with the `set` +operation. Instead, it returns output indicating _how_ the operation will change system state when +called without this option. Use this option to preview the changes DSC will make to a system. + +The output for the command when you use this option is the same as without, except that the +`ExecutionType` metadata field is set to `WhatIf` instead of `Actual`. + +```yaml +Type: Boolean +Mandatory: false +``` + ### -f, --format The `--format` option controls the console output format for the command. If the command output is 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 537a556..9d5df35 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: 05/09/2024 +ms.date: 06/24/2024 ms.topic: reference title: dsc config test --- @@ -52,7 +52,7 @@ resource instances defined in the configuration document saved as `example.dsc.c $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Windows only - type: DSC/AssertionGroup + type: Microsoft.DSC/Assertion properties: $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: @@ -64,9 +64,9 @@ resources: type: Microsoft.Windows/Registry properties: keyPath: HKCU\example - _ensure: Present + _exist: true dependsOn: - - '[DSC/Assertion]Windows only' + - "[resourceId('Microsoft.DSC/Assertion', 'Windows only')" ``` ```sh 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 5703da4..126ff8a 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: 03/06/2024 +ms.date: 06/24/2024 ms.topic: reference title: dsc --- @@ -162,6 +162,11 @@ 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. | +## Notes + +DSC expects input strings to use UTF-8 encoding. When you pass input from stdin or the path to a +file, ensure that the input is encoded as UTF-8. + [01]: completer/command.md [02]: config/command.md [03]: resource/command.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md index 72a51bc..c289574 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource list' command -ms.date: 05/09/2024 +ms.date: 06/24/2024 ms.topic: reference title: dsc resource list --- @@ -45,25 +45,28 @@ dsc resource list ``` ```Output -Type Kind Version Caps RequireAdapter Description ------------------------------------------------------------------------------------------------------------------------------------------------------------------- -DSC.PackageManagement/Brew Resource 0.1.0 gs---e DSC resource to manage Homebrew packages -Microsoft.DSC.Transitional/RunCommandOnSet Resource 0.1.0 gs---- Takes a single-command line to execute on DSC set operation -Microsoft.DSC/Assertion Group 0.1.0 gs-t-- `test` will be invoked for all resources in the supplied configuration. -Microsoft.DSC/Group Group 0.1.0 gs-t-- All resources in the supplied configuration is treated as a group. -Microsoft.DSC/Parallel Group 0.1.0 gs-t-- All resources in the supplied configuration run concurrently. -Microsoft.DSC/PowerShell Adapter 0.1.0 gs-t-e Resource adapter to classic DSC Powershell resources. -Microsoft.Windows/RebootPending Resource 0.1.0 g----- Returns info about pending reboot. -Microsoft.Windows/Registry Resource 0.1.0 gs--d- Manage Windows Registry keys and values -Microsoft.Windows/WindowsPowerShell Adapter 0.1.0 gs-t-- Resource adapter to classic DSC Powershell resources in Windows PowerShell. -Microsoft.Windows/WMI Adapter 0.1.0 g----- Resource adapter to WMI resources. -Microsoft/OSInfo Resource 0.1.0 g----e Returns information about the operating system. -Microsoft/Process Resource 0.1.0 gs-t-e Returns information about running processes. -Test/Delete Resource 0.1.0 g---d- -Test/Echo Resource 0.1.0 gs-t-- -Test/Exist Resource 0.1.0 gsx--- -Test/Sleep Resource 0.1.0 gs-t-- -Test/TestGroup Adapter 0.1.0 g----- +Type Kind Version Caps RequireAdapter Description +-------------------------------------------------------------------------------------------------------------------------------------------------------------------- +Microsoft.DSC.Transitional/RunCommandOnSet Resource 0.1.0 gs------ Takes a single-command line to execute on DSC set operation +Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configuration. +Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. +Microsoft.DSC/Include Import 0.1.0 -------r Allows including a configuration file contents into current configuration. +Microsoft.DSC/Parallel Group 0.1.0 gs--t--- All resources in the supplied configuration run concurrently. +Microsoft.DSC/PowerShell Adapter 0.1.0 gs--t-e- Resource adapter to classic DSC Powershell resources. +Microsoft.Windows/RebootPending Resource 0.1.0 g------- Returns info about pending reboot. +Microsoft.Windows/Registry Resource 0.1.0 gs---d-- Manage Windows Registry keys and values +Microsoft.Windows/WMI Adapter 0.1.0 g------- Resource adapter to WMI resources. +Microsoft.Windows/WindowsPowerShell Adapter 0.1.0 gs--t--- Resource adapter to classic DSC Powershell resources in Windows PowerShell. +Microsoft/OSInfo Resource 0.1.0 g-----e- Returns information about the operating system. +Microsoft/Process Resource 0.1.0 gs--t-e- Returns information about running processes. +Test/Delete Resource 0.1.0 g----d-- +Test/Echo Resource 0.1.0 gs--t--- +Test/Exist Resource 0.1.0 gsx----- +Test/ExitCode Resource 0.1.0 g------- +Test/Sleep Resource 0.1.0 gs--t--- +Test/TestGroup Adapter 0.1.0 g------- +Test/Trace Resource 0.1.0 gs--t--- +Test/WhatIf Resource 0.1.0 gs-w---- ``` ### Example 2 - List a specific resource @@ -76,9 +79,9 @@ dsc resource list Microsoft.DSC/Group ``` ```Output -Type Kind Version Caps RequireAdapter Description -------------------------------------------------------------------------------------------------------------------------------- -Microsoft.DSC/Group Group 0.1.0 gs-t-- All resources in the supplied configuration is treated as a group. +Type Kind Version Caps RequireAdapter Description +--------------------------------------------------------------------------------------------------------------------------------- +Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. ``` ### Example 3 - List resources with a matching type name @@ -91,12 +94,13 @@ dsc resource list Microsoft.DSC/* ``` ```Output -Type Kind Version Caps RequireAdapter Description -------------------------------------------------------------------------------------------------------------------------------------------- -Microsoft.DSC/Assertion Group 0.1.0 gs-t-- `test` will be invoked for all resources in the supplied configuration. -Microsoft.DSC/Group Group 0.1.0 gs-t-- All resources in the supplied configuration is treated as a group. -Microsoft.DSC/Parallel Group 0.1.0 gs-t-- All resources in the supplied configuration run concurrently. -Microsoft.DSC/PowerShell Adapter 0.1.0 gs-t-e Resource adapter to classic DSC Powershell resources. +Type Kind Version Caps RequireAdapter Description +------------------------------------------------------------------------------------------------------------------------------------------------ +Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configuration. +Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. +Microsoft.DSC/Include Import 0.1.0 -------r Allows including a configuration file contents into current configuration. +Microsoft.DSC/Parallel Group 0.1.0 gs--t--- All resources in the supplied configuration run concurrently. +Microsoft.DSC/PowerShell Adapter 0.1.0 gs--t-e- Resource adapter to classic DSC Powershell resources. ``` ### Example 4 - List resources with a matching description @@ -109,11 +113,11 @@ dsc resource list --description 'supplied configuration' ``` ```Output -Type Kind Version Caps RequireAdapter Description ----------------------------------------------------------------------------------------------------------------------------------------- -Microsoft.DSC/Assertion Group 0.1.0 gs-t-- `test` will be invoked for all resources in the supplied configuration. -Microsoft.DSC/Group Group 0.1.0 gs-t-- All resources in the supplied configuration is treated as a group. -Microsoft.DSC/Parallel Group 0.1.0 gs-t-- All resources in the supplied configuration run concurrently. +Type Kind Version Caps RequireAdapter Description +------------------------------------------------------------------------------------------------------------------------------------------ +Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configuration. +Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. +Microsoft.DSC/Parallel Group 0.1.0 gs--t--- All resources in the supplied configuration run concurrently. ``` ### Example 5 - List resources with matching tags @@ -126,10 +130,10 @@ dsc resource list --tags Windows --tags Linux ``` ```output -Type Kind Version Caps RequireAdapter Description ----------------------------------------------------------------------------------------------------------------------- -Microsoft.Windows/Registry Resource 0.1.0 gs--d- Manage Windows Registry keys and values -Microsoft/OSInfo Resource 0.1.0 g----e Returns information about the operating system. +Type Kind Version Caps RequireAdapter Description +------------------------------------------------------------------------------------------------------------------------ +Microsoft.Windows/Registry Resource 0.1.0 gs---d-- Manage Windows Registry keys and values +Microsoft/OSInfo Resource 0.1.0 g-----e- Returns information about the operating system. ``` ### Example 6 - List resources for a specific adapter @@ -140,40 +144,69 @@ adds the returned list of adapted resources to the discovered resource list. DSC further filters specified with the command after this enumeration. ```sh -dsc resource list --adapter Microsoft.DSC/PowerShell +dsc resource list --adapter Microsoft.Windows/WindowsPowerShell ``` ```Output -Type Kind Version Caps RequireAdapter Description ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -PSDscResources/Archive Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/Environment Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/Group Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/MsiPackage Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/Registry Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/Script Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/Service Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/User Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/WindowsFeature Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/WindowsOptionalFeature Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/WindowsPackageCab Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/WindowsProcess Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +Type Kind Version Caps RequireAdapter Description +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +PSDesiredStateConfiguration/Archive Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/Environment Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/File Resource 1.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/Group Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/GroupSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/Log Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/Package Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/ProcessSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/Registry Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/Script Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/Service Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/ServiceSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/SignatureValidation Resource 1.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/User Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WaitForAll Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WaitForAny Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WaitForSome Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WindowsFeature Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WindowsFeatureSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WindowsOptionalFeature Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WindowsOptionalFeatureSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WindowsPackageCab Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WindowsProcess Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDscResources/Archive Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/Environment Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/Group Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/MsiPackage Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/Registry Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/Script Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/Service Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/User Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/WindowsFeature Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/WindowsOptionalFeature Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/WindowsPackageCab Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/WindowsProcess Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. ``` This next command specifies the resource name filter `*Windows*`, limiting the list of returned resources: ```sh -dsc resource list --adapter Microsoft.DSC/PowerShell *Windows* +dsc resource list --adapter Microsoft.Windows/WindowsPowerShell *Windows* ``` ```Output -Type Kind Version Caps RequireAdapter Description ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -PSDscResources/WindowsFeature Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/WindowsOptionalFeature Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/WindowsPackageCab Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. -PSDscResources/WindowsProcess Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +Type Kind Version Caps RequireAdapter Description +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +PSDesiredStateConfiguration/WindowsFeature Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WindowsFeatureSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WindowsOptionalFeature Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WindowsOptionalFeatureSet Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WindowsPackageCab Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDesiredStateConfiguration/WindowsProcess Resource 1.1 gs--t--- Microsoft.Windows/WindowsPowerShell +PSDscResources/WindowsFeature Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/WindowsOptionalFeature Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/WindowsPackageCab Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. +PSDscResources/WindowsProcess Resource 2.12.0.0 gs--t--- Microsoft.Windows/WindowsPowerShell This module contains the standard DSC resources. ``` ## Arguments @@ -283,11 +316,14 @@ displayed in the listed order: - `g` indicates that the resource has the [Get capability][05]. - `s` indicates that the resource has the [Set capability][06] - `x` indicates that the resource has the [SetHandlesExist capability][07] - - `t` indicates that the resource has the [Test capability][08] - - `d` indicates that the resource has the [Delete capability][09] - - `e` indicates that the resource has the [Export capability][10] - - For example, the `Microsoft.Windows/Registry` resource has the following capabilities: `gs--d-`, indicating it has the `Get`, `Set`, and `Delete` capabilities. + - `w` indicates that the resource has the [WhatIf capability][08] + - `t` indicates that the resource has the [Test capability][09] + - `d` indicates that the resource has the [Delete capability][10] + - `e` indicates that the resource has the [Export capability][11] + - `r` indicates that the resource has the [Resolve capability][12] + + For example, the `Microsoft.Windows/Registry` resource has the following capabilities: `gs--d-`, + indicating it has the `Get`, `Set`, and `Delete` capabilities. - **RequireAdapter** - The fully qualified type name of the adapter resource that DSC uses to invoke the returned resource. - **Description** - The short description of the resource's purpose and usage. @@ -303,6 +339,8 @@ To display the output objects as either JSON or YAML objects in the console, use [05]: ../../schemas/outputs/resource/list.md#capability-get [06]: ../../schemas/outputs/resource/list.md#capability-set [07]: ../../schemas/outputs/resource/list.md#capability-sethandlesexist -[08]: ../../schemas/outputs/resource/list.md#capability-test -[09]: ../../schemas/outputs/resource/list.md#capability-delete -[10]: ../../schemas/outputs/resource/list.md#capability-export +[08]: ../../schemas/outputs/resource/list.md#capability-whatif +[09]: ../../schemas/outputs/resource/list.md#capability-test +[10]: ../../schemas/outputs/resource/list.md#capability-delete +[11]: ../../schemas/outputs/resource/list.md#capability-export +[12]: ../../schemas/outputs/resource/list.md#capability-resolve diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/schema.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/schema.md index 282ce3a..1073b1c 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/schema.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/schema.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource schema' command -ms.date: 03/06/2024 +ms.date: 06/24/2024 ms.topic: reference title: dsc resource schema --- @@ -40,44 +40,124 @@ dsc resource schema --resource Microsoft/OSInfo ```yaml $schema: http://json-schema.org/draft-07/schema# +$id: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/resources/Microsoft/OSInfo/v0.1.0/schema.json title: OsInfo +description: | + Returns information about the operating system. + + https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource +markdownDescription: | + The `Microsoft/OSInfo` resource enables you to assert whether a machine meets criteria related to + the operating system. The resource is only capable of assertions. It doesn't implement the set + operation and can't configure the operating system. + + [Online documentation][01] + + [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource type: object required: [] +additionalProperties: false properties: $id: type: string + readOnly: true + title: Data Type ID + description: | + Returns the unique ID for the OSInfo instance data type. + + https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#id + markdownDescription: | + Returns the unique ID for the OSInfo instance data type. + + [Online documentation][01] + + [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#id architecture: - type: - - string - - 'null' - bitness: - $ref: '#/definitions/Bitness' - codename: - type: - - string - - 'null' - edition: - type: - - string - - 'null' - family: - $ref: '#/definitions/Family' - version: type: string -additionalProperties: false -definitions: - Bitness: + title: Processor architecture + description: | + Defines the processor architecture as reported by 'uname -m' on the operating system. + + https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#architecture + markdownDescription: | + Defines the processor architecture as reported by `uname -m` on the operating system. + + [Online documentation][01] + + [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#architecture + bitness: type: string enum: - '32' - '64' - unknown - Family: + title: Operating system bitness + description: | + Defines whether the operating system is a 32-bit or 64-bit operating system. + + https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#bitness + markdownDescription: | + Defines whether the operating system is a 32-bit or 64-bit operating system. + + [Online documentation][01] + + [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#bitness + codename: + type: string + title: Linux codename + description: | + Defines the codename for the operating system as returned from 'lsb_release --codename'. + + https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#codename + markdownDescription: | + Defines the codename for the operating system as returned from `lsb_release --codename`. + + [Online documentation][01] + + [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#codename + edition: + type: string + title: Windows edition + description: | + Defines the operating system edition, like 'Windows 11' or 'Windows Server 2016'. + + https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#edition + markdownDescription: | + Defines the operating system edition, like `Windows 11` or `Windows Server 2016`. + + [Online documentation][01] + + [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#edition + family: type: string enum: - Linux - - MacOS + - macOS - Windows + title: Operating system family + description: | + Defines whether the operating system is Linux, macOS, or Windows. + + https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#family + markdownDescription: | + Defines whether the operating system is Linux, macOS, or Windows. + + [Online documentation][01] + + [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#family + version: + type: string + title: Operating system version + description: | + Defines the version of the operating system as a string. + + https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#version + markdownDescription: | + Defines the version of the operating system as a string. + + [Online documentation][01] + + [01]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource#version ``` ## Options diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/command.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/command.md index 5bdb0a5..343cd5c 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/command.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/command.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc schema' command -ms.date: 03/06/2024 +ms.date: 06/24/2024 ms.topic: reference title: dsc schema --- @@ -37,13 +37,117 @@ dsc schema --type get-result ```yaml $schema: http://json-schema.org/draft-07/schema# title: GetResult -type: object -required: -- actualState -properties: - actualState: - description: The state of the resource as it was returned by the Get method. -additionalProperties: false +anyOf: +- $ref: '#/definitions/ResourceGetResponse' +- type: array + items: + $ref: '#/definitions/ResourceGetResult' +definitions: + ResourceGetResponse: + type: object + required: + - actualState + properties: + actualState: + description: The state of the resource as it was returned by the Get method. + additionalProperties: false + ResourceGetResult: + type: object + required: + - name + - result + - type + properties: + metadata: + anyOf: + - $ref: '#/definitions/Metadata' + - type: 'null' + name: + type: string + type: + type: string + result: + $ref: '#/definitions/GetResult' + additionalProperties: false + Metadata: + type: object + properties: + Microsoft.DSC: + anyOf: + - $ref: '#/definitions/MicrosoftDscMetadata' + - type: 'null' + MicrosoftDscMetadata: + type: object + properties: + version: + description: Version of DSC + type: + - string + - 'null' + operation: + description: The operation being performed + anyOf: + - $ref: '#/definitions/Operation' + - type: 'null' + executionType: + description: The type of execution + anyOf: + - $ref: '#/definitions/ExecutionKind' + - type: 'null' + startDatetime: + description: The start time of the configuration operation + type: + - string + - 'null' + endDatetime: + description: The end time of the configuration operation + type: + - string + - 'null' + duration: + description: The duration of the configuration operation + type: + - string + - 'null' + securityContext: + description: The security context of the configuration operation, can be specified to be required + anyOf: + - $ref: '#/definitions/SecurityContextKind' + - type: 'null' + context: + description: Identifies if the operation is part of a configuration + anyOf: + - $ref: '#/definitions/ContextKind' + - type: 'null' + Operation: + type: string + enum: + - Get + - Set + - Test + - Export + ExecutionKind: + type: string + enum: + - Actual + - WhatIf + SecurityContextKind: + type: string + enum: + - Current + - Elevated + - Restricted + ContextKind: + type: string + enum: + - Configuration + - Resource + GetResult: + anyOf: + - $ref: '#/definitions/ResourceGetResponse' + - type: array + items: + $ref: '#/definitions/ResourceGetResult' ``` ## Options diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/int.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/int.md index 3af4080..2e84dc9 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/int.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/int.md @@ -1,6 +1,6 @@ --- description: Reference for the 'int' DSC configuration document function -ms.date: 05/09/2024 +ms.date: 06/24/2024 ms.topic: reference title: int --- @@ -9,7 +9,7 @@ title: int ## Synopsis -Returns an integer from an input string or non-integer number. +Returns an integer from an input string or integer. ## Syntax @@ -19,8 +19,9 @@ int() ## Description -The `int()` function returns an integer, converting an input string or non-integer number into an -integer. It truncates the fractional part of the input number, it doesn't round up. +The `int()` function returns an integer, converting an input string into an integer. If you pass an +integer, it returns the integer. If you pass any other value, including a non-integer number, the +function raises an invalid input error. ## Examples @@ -57,17 +58,12 @@ hadErrors: false ### inputValue -The `int()` function expects input as either a string or a number. If the value is a string that -can't be parsed as a number, DSC returns an error for the function. - -> [!NOTE] -> There is an open bug (see [GitHub issue #390][#390]) for this function when operating on numbers. -> The function correctly returns the expected value for string representations of numbers with -> fractional parts, but returns the fractional part instead of the integer for actual numbers. -> Specify the input value for this function as a string instead of a number. +The `int()` function expects input as either a string or an integer. If the value is a string that +can't be parsed as a number DSC returns an error for the function. If the value isn't a string or +integer, DSC returns an invalid input error for the function. ```yaml -Type: [String, Number] +Type: [String, Integer] Required: true MinimumCount: 1 MaximumCount: 1 @@ -84,4 +80,3 @@ Type: integer ``` -[#390]: https://github.com/PowerShell/DSC/issues/390 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 46097e3..0e25e2a 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: 05/09/2024 +ms.date: 06/24/2024 ms.topic: reference title: DSC Configuration document parameter schema --- @@ -74,7 +74,7 @@ independent logging or recording that isn't handled by DSC, the value may be sto Use secure strings for passwords and secrets. For more information about data types, see -[DSC configuration parameter data type schema reference][02]. +[DSC configuration parameter data type schema reference][03]. ```yaml Type: string diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md index 8f34dd5..a60b068 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for resource kind -ms.date: 05/09/2024 +ms.date: 06/24/2024 ms.topic: reference title: DSC Resource kind schema reference --- @@ -17,7 +17,7 @@ Identifies whether a resource is an adapter resource, a group resource, or a nor SchemaDialect: https://json-schema.org/draft/2020-12/schema SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json Type: string -ValidValues: [Resource, Adapter, Group] +ValidValues: [Resource, Adapter, Group, Import] ``` ## Description @@ -27,6 +27,7 @@ DSC supports three kinds of command-based DSC Resources: - `Resource` - Indicates that the manifest isn't for a group or adapter resource. - `Group` - Indicates that the manifest is for a [group resource](#group-resources). - `Adapter` - Indicates that the manifest is for an [adapter resource](#adapter-resources). +- `Import` - Indicates that the manifest is for an [importer resource](#importer-resources). When `kind` isn't defined in the resource manifest, DSC infers the value for the property. If the `adapter` property is defined in the resource manifest, DSC infers the value of `kind` as @@ -54,16 +55,39 @@ modules. They don't define resource manifests. Group resources always operate on nested DSC Resource instances. Group resources can change how the nested instances are processed, like the `Microsoft.DSC/Assertion` group resource. +A group resource must always define the [kind][03] property in the resource manifest. + Group resources can also be used to bundle sets of resources together for processing, like the -`Microsoft.DSC/Group` resource. You can use the [dependsOn][03] property for a resource instance in +`Microsoft.DSC/Group` resource. You can use the [dependsOn][04] property for a resource instance in a configuration to point to a group resource instead of enumerating each resource in the list. +### Importer resources + +Importer resources resolve an external source to a set of nested DSC Resource instances. The +properties of an importer resource define how to find and resolve the external source. + +An importer resource must always define the [kind][03] and [resolve][05] properties in the resource +manifest. + +For example, the `Microsoft.DSC/Import` importer resource resolves instances from an external +configuration document, enabling you to compose configurations from multiple files. + ### Nested resource instances -The resource instances declared in both adapter and group resources are called _nested resource -instances_. For nested instances, a resource instance is _adjacent_ if it's declared in the same -group or adapter instance. A resource instance is _external_ to a nested instance if it's declared -outside of the group or adapter instance, or nested inside an adjacent group or adapter instance. +The resource instances declared in adapter and group resources or resolved by importer resources +are called _nested resource instances_. + +For nested instances, a resource instance is _adjacent_ if: + +- It's declared in the same group or adapter instance. +- It's resolved by the same importer instance. + +A resource instance is _external_ to a nested instance if: + +- It's declared outside of the group or adapter instance +- It's resolved by a different importer instance +- It's nested inside an adjacent group, adapter, or importer instance. + For top-level instances, other instances at the top-level are adjacent. All other instances are external. @@ -118,18 +142,18 @@ The following matrix defines the relations of each instance in the configuration ### Referencing nested instances -Nested resource instances have limitations for the [dependsOn][03] property and the -[reference()][04] configuration function. +Nested resource instances have limitations for the [dependsOn][04] property and the +[reference()][06] configuration function. 1. You can only reference adjacent instances. You can't reference a nested instance from outside of - the group or adapter that declares it. You can't use a reference to a resource outside of the - group or adapter resource for a nested instance. + the instance that declares or resolves it. You can't use a reference to a resource outside of the + group, adapter, or importer resource for a nested instance. 1. You can only use the `dependsOn` property for adjacent instances. You must add a dependency on - the group or adapter instance, not a nested instance of the group or adapter. Nested instances - can't depend on external instances. + the group, adapter, or importer instance, not a nested instance. Nested instances can't depend + on external instances. The following examples show valid and invalid references and dependencies. The examples use the -`Microsoft.DSC/Group` resource, but the functionality is the same for adapter resources. +`Microsoft.DSC/Group` resource, but the functionality is the same for adapter and import resources. #### Example 1 - Valid references and dependencies @@ -357,5 +381,7 @@ resources: [01]: ../resource/manifest/adapter.md [02]: ../resource/manifest/validate.md -[03]: ../config/resource.md#dependson -[04]: ../config/functions/reference.md +[03]: ../resource/manifest/root.md#kind +[04]: ../config/resource.md#dependson +[05]: ../resource/manifest/resolve.md +[06]: ../config/functions/reference.md 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 5480fe4..b658e90 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: 05/09/2024 +ms.date: 06/24/2024 ms.topic: reference title: dsc config get result schema reference --- @@ -55,7 +55,7 @@ The metadata under this property describes the context of the overall operation: `Set`, `Test`, or `Export`. - [executionType][03] defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` - operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` + operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--what-if` argument. - [startDatetime][04] defines the start date and time for the DSC operation as a timestamp following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like 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 cf5f0f2..61b760b 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: 05/09/2024 +ms.date: 06/24/2024 ms.topic: reference title: dsc config set result schema reference --- @@ -56,7 +56,7 @@ The metadata under this property describes the context of the overall operation: `Set`, `Test`, or `Export`. - [executionType][03] defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` - operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` + operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--what-if` argument. - [startDatetime][04] defines the start date and time for the DSC operation as a timestamp following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like 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 a97cea9..1086875 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: 05/09/2024 +ms.date: 06/24/2024 ms.topic: reference title: dsc config test result schema reference --- @@ -56,7 +56,7 @@ The metadata under this property describes the context of the overall operation: `Set`, `Test`, or `Export`. - [executionType][03] defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` - operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` + operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--what-if` argument. - [startDatetime][04] defines the start date and time for the DSC operation as a timestamp following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like 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 f9e642e..2191ba2 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: 05/09/2024 +ms.date: 06/24/2024 ms.topic: reference title: dsc resource list result schema reference --- @@ -85,45 +85,64 @@ optional and depend on the resource. The following list describes the available capabilities for a resource: -- `Get` - The resource supports retrieving the current state of an +- `Get` - The resource supports retrieving the current state of an instance. All DSC Resources must have this capability. A resource has this capability when it defines the mandatory [get][07] property in its resource manifest. -- `Set` - The resource supports enforcing the desired state of an +- `Set` - The resource supports enforcing the desired state of an instance. A resource has this capability when it defines the [set][08] property in its resource manifest. Resources without this capability can't be used with the [dsc resource set][09] or - [dsc config set][10] commands unless they're in a `Microsoft.DSC/Assertion` group as a nested + [dsc config set][10] commands unless they're in a Microsoft.DSC/Assertion group as a nested instance. -- `SetHandlesExist` - The resource supports the - [_exist property][12] directly. A resource has this capability when it defines the - [handlesExist][13] property as `true` in the definition of the [set][08] command property in its +- `SetHandlesExist` - The resource supports the + [_exist property][11] directly. A resource has this capability when it defines the + [handlesExist][12] property as `true` in the definition of the [set][08] command property in its resource manifest. When a resource has this capability, the `_exist` property is part of the resource's instance schema and the resource handles deleting instances of the resource in its `set` command. When a resource doesn't have this capability, when DSC finds an instance of the resource with - `_exist` set to `false`, it handles calling the [delete][14] operation for the resource. + `_exist` set to `false`, it handles calling the [delete][13] operation for the resource. If the resource doesn't have this capability or the `Delete` capability, DSC raises an error when an instance defines `_exist` as `false`. -- `Test` - The resource supports validating the desired state of an +- `WhatIf` - The resource supports returning explicit information + about how it will modify state when a user calls [dsc config set][10] with the [--what-if][14] + option. A resource has this capability when it defines the [What-if method][15] in its resource + manifest. + + When a resource has this capability, DSC calls the defined command with its arguments when a + user executes the `dsc config set` command with the `--what-if` option. + + When a resource doesn't have this capability, DSC synthesizes how the resource will change and + instance by converting the `Test` result for the instance into a `Set` result. The synthetic + operation can't indicate potential issues or changes that can't be determined by comparing the + result of the `Test` operation against the resource's desired state. For example, the credentials + used to test a resource might be valid for that operation, but not have permissions to actually + modify the system state. Only a resource with this capability can fully report whether and how + the resource will change system state. +- `Test` - The resource supports validating the desired state of an instance against the current state of the instance. A resource has this capability when it - defines the [test][15] property in its resource manifest. + defines the [test][16] property in its resource manifest. If a resource doesn't have the `Test` capability, DSC uses a synthetic test for instances of the resource. The synthetic test compares each property for the desired state of an instance against the actual state. The synthetic test uses strict, case-sensitive equivalence. If the desired state for a property and the actual state aren't the same, DSC marks the property as out of the desired state. -- `Delete` - The resource supports removing an instance. A resource - has this capability when it defines the [delete][14] property in its resource manifest. This +- `Delete` - The resource supports removing an instance. A resource + has this capability when it defines the [delete][13] property in its resource manifest. This capability isn't mutually exclusive with the `SetHandlesExist` property. A resource can handle - the `_exist` property in set operations and be called directly with [dsc resource delete][16] to + the `_exist` property in set operations and be called directly with [dsc resource delete][17] to remove an instance. -- `Export` - The resource supports enumerating every instance of the - resource. A resource has this capability when it defines the [export][17] property in its resource - manifest. Only resources with this capability are usable with the [dsc resource export][18] and - [dsc config export][19] commands. +- `Export` - The resource supports enumerating every instance of + the resource. A resource has this capability when it defines the [export][18] property in its + resource manifest. Only resources with this capability are usable with the + [dsc resource export][19] and [dsc config export][20] commands. +- `Resolve` - The resource supports resolving nested resource + instances from an external source. A resource has this capability when it defines the + [resolve][21] property in its resource manifest. This functionality is primarily used by + [importer resources][22]. ```yaml Type: array @@ -211,7 +230,7 @@ Required: true Represents the values defined in the resource's manifest. This value is `null` for resources that aren't command-based. For more information on the value for this property, see -[Command-based DSC Resource manifest schema reference][20]. +[Command-based DSC Resource manifest schema reference][23]. ```yaml Type: [object, 'null'] @@ -229,13 +248,16 @@ Required: true [08]: ../../resource/manifest/set.md [09]: ../../../cli/resource/set.md [10]: ../../../cli/config/set.md -[11]: ../../../microsoft.dsc/Assertion/resource.md -[12]: ../../resource/properties/exist.md -[13]: ../../resource/manifest/set.md#handlesexist -[14]: ../../resource/manifest/delete.md -[15]: ../../resource/manifest/test.md -[16]: ../../../cli/resource/delete.md -[17]: ../../resource/manifest/export.md -[18]: ../../../cli/resource/export.md -[19]: ../../../cli/config/export.md -[20]: ../../resource/manifest/root.md +[11]: ../../resource/properties/exist.md +[12]: ../../resource/manifest/set.md#handlesexist +[13]: ../../resource/manifest/delete.md +[14]: ../../../cli/config/set.md#-w---what-if +[15]: ../../resource/manifest/whatif.md +[16]: ../../resource/manifest/test.md +[17]: ../../../cli/resource/delete.md +[18]: ../../resource/manifest/export.md +[19]: ../../../cli/resource/export.md +[20]: ../../../cli/config/export.md +[21]: ../../resource/manifest/resolve.md +[22]: ../../definitions/resourceKind.md#importer-resources +[23]: ../../resource/manifest/root.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/resolve.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/resolve.md new file mode 100644 index 0000000..99b2c61 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/resolve.md @@ -0,0 +1,160 @@ +--- +description: JSON schema reference for the 'resolve' property in a DSC Resource manifest +ms.date: 01/17/2024 +ms.topic: reference +title: DSC Resource manifest resolve property schema reference +--- + +# DSC Resource manifest resolve property schema reference + +## Synopsis + +Indicates how to call the resource to resolve a nested configuration document from an external +source. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.resolve.json +Type: object +``` + +## Description + +Defines how DSC must call the DSC Resource to resolve an external source to nested DSC +Configuration Document. Define this method for [importer resources][01] and set the [kind][02] +property in the manifest root to `Import`. + +DSC sends data to the command in three ways: + +1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. +1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. +1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. You can only define one JSON input argument for a command. + +You must define the `input` property, one JSON input argument in the `args` property array, or +both. + +## Required properties + +The `resolve` definition must include these properties: + +- [executable](#executable) + +## Properties + +### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the command. A +file extension is only required when the command isn't recognizable by the operating system as an +executable. + +```yaml +Type: string +Required: true +``` + +### args + +The `args` property defines the list of arguments to pass to the command. The arguments can be any +number of strings. If you want to pass the JSON object representing the property bag for the +resource to an argument, you can define a single item in the array as a [JSON object], indicating the +name of the argument with the `jsonInputArg` string property and whether the argument is mandatory +for the command with the `mandatory` boolean property. + +```yaml +Type: array +Required: false +Default: [] +Type: [string, object(JSON Input Argument)] +``` + +#### String arguments + +Any item in the argument array can be a string representing a static argument to pass to the +command, like `config` or `--format`. + +```yaml +Type: string +``` + +#### JSON input argument + +Defines an argument for the command that accepts the JSON input object as a string. DSC passes the +JSON input to the named argument when available. A JSON input argument is defined as a JSON object +with the following properties: + +- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. +- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, + even when there's no JSON input for the command. In that case, DSC passes an empty string to the + JSON input argument. + +You can only define one JSON input argument per arguments array. + +If you define a JSON input argument and an `input` kind for a command, DSC sends the JSON data both +ways: + +- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable for + each property in the JSON input and passes the JSON input object as a string to the defined + argument. +- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over stdin + and as a string to the defined argument. +- If you define a JSON input argument without defining the `input` property, DSC only passes the + JSON input as a string to the defined argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. This makes the manifest invalid. You must define the `input` property, +a JSON input argument in the `args` property array, or both. + +```yaml +Type: object +RequiredProperties: [jsonInputArg] +``` + +### input + +The `input` property defines how to pass input to the resource. If this property isn't defined and +the definition doesn't define a [JSON input argument](#json-input-argument), DSC doesn't send any +input to the resource when invoking the `resolve` operation. + +The value of this property must be one of the following strings: + +- `env` - Indicates that the resource expects the properties of an instance to be specified as + environment variables with the same names and casing. + + This option only supports the following data types for instance properties: + + - `boolean` + - `integer` + - `number` + - `string` + - `array` of `integer` values + - `array` of `number` values + - `array` of `string` values + + For non-array values, DSC sets the environment variable to the specified value as-is. When the + data type is an array of values, DSC sets the environment variable as a comma-delimited string. + For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo` environment + variable as `"1,2,3"`. + + If the resource needs to support complex properties with an `object` value or multi-type arrays, + set this to `stdin` instead. +- `stdin` - Indicates that the resource expects a JSON blob representing an instance from `stdin`. + The JSON must adhere to the instance schema for the resource. + +```yaml +Type: string +Required: false +ValidValues: [env, stdin] +``` + + +[01]: ../../definitions/resourceKind.md#importer-resources +[02]: ./root.md#kind 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 cb21668..56f803e 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 @@ -210,6 +210,18 @@ Type: object Required: false ``` +### whatIf + +Defines how DSC must call the DSC Resource to indicate whether and how the set command will modify +an instance and how to process the output from the DSC Resource. If a resource doesn't define this +method in the manifest, DSC synthesizes this behavior by converting the result of the test +operation for the resource into the set result. + +The value of this property must be an object. The `executable` property, defining the name of the +command to call, is mandatory. The `args` `input`, `implementsPretest`, and `returns` properties +are optional. For more information, see +[DSC Resource manifest whatIf property schema reference][10]. + ### test The `test` property defines how to call the resource to test whether an instance is in the desired @@ -218,7 +230,7 @@ property isn't defined, DSC performs a basic synthetic test for instances of the The value of this property must be an object. The object's `executable` property, defining the name of the command to call, is mandatory. The `args` `input`, and `returns` properties are optional. -For more information, see [DSC Resource manifest test property schema reference][10]. +For more information, see [DSC Resource manifest test property schema reference][11]. ```yaml Type: object @@ -232,7 +244,7 @@ property is mandatory for DSC Group Resources. DSC ignores this property for all The value of this property must be an object. The object's `executable` property, defining the name of the command to call, is mandatory. The `args` property is optional. For more information, see -[DSC Resource manifest validate property schema reference][11]. +[DSC Resource manifest validate property schema reference][12]. ```yaml Type: object @@ -246,7 +258,7 @@ When specified, the `provider` property defines the resource as a DSC Resource P The value of this property must be an object. The object's `list` and `config` properties are mandatory. The `list` property defines how to call the provider to return the resources that the provider can manage. The `config` property defines how the provider expects input. For more -information, see the [DSC Resource manifest provider property schema reference][12]. +information, see the [DSC Resource manifest provider property schema reference][13]. ### exitCodes @@ -277,7 +289,7 @@ DSC interprets exit code `0` as a successful operation and any other exit code a ```yaml Type: object Required: false -PropertyNamePattern: ^[0-9]+# +PropertyNamePattern: ^-?[0-9]+# PropertyValueType: string ``` @@ -291,7 +303,7 @@ resource. This property must always be an object that defines one of the followi - `embedded` - When you specify the `embedded` property, DSC uses the defined value as the JSON schema. -For more information, see [DSC Resource manifest schema property reference][13]. +For more information, see [DSC Resource manifest schema property reference][14]. ```yaml Type: object @@ -307,7 +319,8 @@ Required: true [07]: export.md [08]: get.md [09]: set.md -[10]: test.md -[11]: validate.md -[12]: adapter.md -[13]: schema/property.md +[10]: whatif.md +[11]: test.md +[12]: validate.md +[13]: provider.md +[14]: schema/property.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md new file mode 100644 index 0000000..ed5054e --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md @@ -0,0 +1,283 @@ +--- +description: JSON schema reference for the 'whatIf' property in a DSC Resource manifest +ms.date: 01/17/2024 +ms.topic: reference +title: DSC Resource manifest whatIf property schema reference +--- + +# DSC Resource manifest whatIf property schema reference + +## Synopsis + +Defines how to indicate whether and how the set command will modify an instance. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.whatIf.json +Type: object +``` + +## Description + +When enforcing a configuration document with the [dsc config set][01] command, users can specify +the [--what-if][02] option to see whether and how resources will change system state without +actually doing so. This property defines how DSC can invoke the resource to return that information +directly. + +When this property isn't defined, DSC synthesizes this behavior by converting the result of a test +operation against the resource into a set result. The synthetic result can only indicate how the +operation will change the resource properties. It can't indicate whether the `set` operation will +fail due to invalid parameters or which read-only properties the resource will return from the +operation. The following list describes a few cases where a synthetic what-if result won't return +sufficient information to the user: + +- A resource requiring a credential parameter might successfully test the instance but not have + permissions to modify it. In this case, the user might run `dsc config set --what-if` and see an + apparently successful prediction for the resource. Then, when they run the command without the + `--what-if` option, the resource raises an error that the user has to investigate. If any other + resources applied successfully before the instance that failed, the system might be left in a + partially-configured state. +- A resource with a dependency service won't be able to report whether that service needs to be + restarted from a synthetic result. After reviewing the impact of the configuration based on the + what-if result, a user might then inadvertently restart a service or leave the configuration in a + partially-configured state until that service is rebooted. + +If your resource uses parameters or returns read-only properties from a `set` operation, define this +method to ensure your users get the best information about whether and how the resource will modify +system state in what-if mode. + +DSC sends data to the command in three ways: + + 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. + 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. + 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a + string representing the data as a compressed JSON object to the specified argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. You can only define one JSON input argument for a command. + +You must define the `input` property, one JSON input argument in the `args` property array, or +both. + +## Examples + +### Example 1 - Full definition + +```json +"set": { + "executable": "my_app", + "args": [ + "config", + "set", + "--what-if" + ], + "input": "stdin", + "return": "state" +} +``` + +It defines `executable` as `my_app`, rather than `my_app.exe`. The extension isn't required when +the operating system recognizes the command as an executable. + +The manifest defines three arguments, `config`, `set`, and `--what-if`. The value of the `input` +property indicates that the `whatIf` command expects its input as a JSON blob from `stdin`. + +Combined with the value for `executable`, DSC calls the what-if method for this resource by +running: + +```sh +{ ... } | my_app config set --what-if +``` + +The manifest defines `return` as `state`, indicating that it only returns the expected final state +of the resource after the `set` method runs. DSC compares the desired state to the return data of +this resource to identify which of the resource's properties the `set` method will enforce, if any. + +## Required Properties + +The `whatIf` definition must include these properties: + +- [executable](#executable) + +## Properties + +### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the command. A +file extension is only required when the command isn't recognizable by the operating system as an +executable. + +```yaml +Type: string +Required: true +``` + +### args + +The `args` property defines the list of arguments to pass to the command. The arguments can be any +number of strings. If you want to pass the JSON object representing the property bag for the +resource to an argument, you can define a single item in the array as a JSON object, indicating the +name of the argument with the `jsonInputArg` string property and whether the argument is mandatory +for the command with the `mandatory` boolean property. + +```yaml +Type: array +Required: false +Default: [] +Type: [string, object(JSON Input Argument)] +``` + +#### String arguments + +Any item in the argument array can be a string representing a static argument to pass to the +command, like `config` or `--format`. + +```yaml +Type: string +``` + +#### JSON input argument + +Defines an argument for the command that accepts the JSON input object as a string. DSC passes the +JSON input to the named argument when available. A JSON input argument is defined as a JSON object +with the following properties: + +- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. +- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, + even when there's no JSON input for the command. In that case, DSC passes an empty string to the + JSON input argument. + +You can only define one JSON input argument per arguments array. + +If you define a JSON input argument and an `input` kind for a command, DSC sends the JSON data both +ways: + +- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable for + each property in the JSON input and passes the JSON input object as a string to the defined + argument. +- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over stdin + and as a string to the defined argument. +- If you define a JSON input argument without defining the `input` property, DSC only passes the + JSON input as a string to the defined argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. This makes the manifest invalid. You must define the `input` property, +a JSON input argument in the `args` property array, or both. + +```yaml +Type: object +RequiredProperties: [jsonInputArg] +``` + +### input + +The `input` property defines how to pass input to the resource. If this property isn't defined and +the definition doesn't define a [JSON input argument](#json-input-argument), DSC doesn't send any +input to the resource when invoking the `whatIf` operation. + +The value of this property must be one of the following strings: + +- `env` - Indicates that the resource expects the properties of an instance to be specified as + environment variables with the same names and casing. + + This option only supports the following data types for instance properties: + + - `boolean` + - `integer` + - `number` + - `string` + - `array` of `integer` values + - `array` of `number` values + - `array` of `string` values + + For non-array values, DSC sets the environment variable to the specified value as-is. When the + data type is an array of values, DSC sets the environment variable as a comma-delimited string. + For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo` environment + variable as `"1,2,3"`. + + If the resource needs to support complex properties with an `object` value or multi-type arrays, + set this to `stdin` instead. +- `stdin` - Indicates that the resource expects a JSON blob representing an instance from `stdin`. + The JSON must adhere to the instance schema for the resource. + +```yaml +Type: string +Required: false +ValidValues: [env, stdin] +``` + +### 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. In most cases, this value should be set the same as the `implementsPretest` property in +the definition for the [set method][03] in the resource manifest. + +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 default value is `false`. + +```yaml +Type: boolean +Required: false +Default: false +``` + +### handlesExist + +The `handlesExist` property defines whether the resource has built-in handling for the +[_exist][04] property in the `set` operation. The default value is `false`. In most cases, this +value should be set the same as the `implementsPretest` property in the definition for the +[set method][03] in the resource manifest. + +Set this property to `true` when the resource meets the following implementation requirements: + +- The resource's [instance schema][05] defines the `_exist` property as a valid instance property. +- The resource's `set` command handles creating, updating, and deleting an instance based on the + current state of the instance and the value of the `_exist` property in the desired state. + +When this property is set to `true`, the resource indicates that it has the [SetHandlesExist][06] +[capability][07]. When processing resources with the `SetHandlesExist` capability in a +configuration, DSC calls the `set` operation for the resource when an instance defines `_exist` as +`false`. Without this capability, a resource must define the [delete][08] operation to support +removing instances of the resource. + +If a resource manifest doesn't define this property as `true` and doesn't define the `delete` +operation, DSC raises an error when it encounters an instance of the resource with `_exist` set to +`false`. + +### return + +The `return` property defines how DSC should process the output for this method. The value of this +property must be one of the following strings: + +- `state` - Indicates that the resource returns only the instance's expected final state after the + set operation as a JSON blob. +- `stateAndDiff` - Indicates that the resource returns the instance's expected final state and an + array of property names that the resource modified. + +The default value is `state`. + +```yaml +Type: string +Required: false +Default: state +ValidValues: [state, stateAndDiff] +``` + + +[01]: ../../../cli/config/set.md +[02]: ../../../cli/config/set.md#-w---what-if +[03]: ./set.md +[04]: ../properties/exist.md +[05]: ./root.md#schema-1 +[06]: ../../outputs/resource/list.md#capability-sethandlesexist +[07]: ../../outputs/resource/list.md#capabilities +[08]: ./delete.md