diff --git a/docs/reference/schemas/resource/manifest/adapter.md b/docs/reference/schemas/resource/manifest/adapter.md index 64926a33d..afc43522d 100644 --- a/docs/reference/schemas/resource/manifest/adapter.md +++ b/docs/reference/schemas/resource/manifest/adapter.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'adapter' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest adapter property schema reference --- @@ -23,7 +23,9 @@ Type: object DSC Resource Adapters must define the `adapter` property in their manifest. This property identifies the resource as an adapter and defines how DSC can call the adapter to get the resources -the adapter supports and how to pass resource instances to the adapter. +the adapter supports and how to pass resource instances to the adapter. When a manifest defines +this property and doesn't define the [kind][01] property, DSC infers the resource kind as +`adapter`. ## Examples @@ -39,16 +41,18 @@ This example is from the `Microsoft.DSC/PowerShell` DSC Resource Adapter. "-NoLogo", "-NonInteractive", "-NoProfile", + "-ExecutionPolicy", + "Bypass", "-Command", - "./powershell.resource.ps1 List" + "./psDscAdapter/powershell.resource.ps1 List" ] - }, - "config": "full" -}, + }, + "inputKind": "full" +} ``` -The manifest sets `config` to `full`, indicating that the adapter expects a JSON blob representing -the full and unprocessed configuration from `stdin`. +The manifest sets `inputKind` to `full`, indicating that the adapter expects a JSON blob +representing the full and unprocessed configuration from `stdin`. It defines `list.executable` as `pwsh`. The arguments defined in `list.args` ensure that DSC runs PowerShell: @@ -56,47 +60,95 @@ PowerShell: - Without the logo banner - In non-interactive mode - Without loading any profile scripts -- To invoke the `powershell.resource.ps1` script in the same folder as the `dsc` command and - pass the `List` argument. +- With the execution policy set to `Bypass` +- To invoke the `powershell.resource.ps1` script in the `psDscAdapter` folder next to the manifest + and pass the `List` argument. With this definition, DSC calls the `list` method for this adapter by running: ```sh -pwsh -NoLogo -NonInteractive -NoProfile -Command "./powershellgroup.resource.ps1 List" +pwsh -NoLogo -NonInteractive -NoProfile -ExecutionPolicy Bypass \ + -Command "./psDscAdapter/powershell.resource.ps1 List" ``` -## Required Properties +### Example 2 - Microsoft.Adapter/PowerShell + +This example is from the `Microsoft.Adapter/PowerShell` DSC Resource Adapter. + +```json +"adapter": { + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-ExecutionPolicy", + "Bypass", + "-Command", + "./psDscAdapter/powershell.resource.ps1", + "List", + "-ResourceType", + "Single" + ] + }, + "inputKind": "single" +} +``` + +The manifest sets `inputKind` to `single`, indicating that DSC should invoke the adapter for one +adapted resource instance at a time. The adapter's `get`, `set`, `test`, and `export` definitions +use the [resource type argument][02] and [resource path argument][03] to identify which adapted +resource to invoke. + +## Required properties The `adapter` definition must include these properties: -- [config](#config) -- [list](#list) +- [inputKind](#inputkind) ## Properties -### config +### inputKind -The `config` property defines how the adapter expects to receive resource configurations. The +The `inputKind` property defines how the adapter expects to receive resource configurations. The value must be one of the following options: - `full` - Indicates that the adapter expects a JSON blob containing the full and unprocessed - configuration as a single JSON blob over `stdin`. + configuration as a single JSON blob over `stdin`. DSC adds a `metadata` property with the + `Microsoft.DSC.context` value set to `configuration` to the input so the adapter can distinguish + a full configuration from a single resource instance. - `sequence` - Indicates that the adapter expects each resource's configuration as a - [JSON Line][01] over `stdin`. + [JSON Line][04] over `stdin`. +- `single` - Indicates that the adapter expects a single adapted resource instance. DSC invokes + the adapter's operation commands directly for each adapted resource instance and passes the + instance properties as the input for the command. Use the [resource type argument][02], + [resource path argument][03], [resource version argument][05], and + [adapted content argument][06] in the operation definitions to tell the adapter which adapted + resource to invoke. + +Prior to DSC version 3.2.0, this property was named `config`. DSC still accepts the `config` name +for backward compatibility, but new manifests should use `inputKind`. ```yaml Type: string -ValidValues: [full, sequence] +Required: true +ValidValues: [full, sequence, single] ``` ### list The `list` property defines how to call the adapter to list the resources it supports. The value -of this property must be an object and define the `executable` sub-property. +of this property must be an object and define the `executable` sub-property. For more information +about the expected output, see [DSC resource list operation stdout schema reference][07]. + +When this property isn't defined, DSC can't discover the adapter's resources by invoking the +adapter. Users can still define adapted resources for the adapter with adapted resource manifests +that specify the adapter with their `requireAdapter` property. ```yaml Type: object -Required: true +Required: false RequiredProperties: [executable] ``` @@ -115,12 +167,21 @@ Required: true #### args The `args` sub-property defines an array of strings to pass as arguments to the command. DSC passes -the arguments to the command in the order they're specified. +the arguments to the command in the order they're specified. Unlike the `args` property for the +operation methods, this array only accepts strings. ```yaml -Type: array -Required: false -Default: [] +Type: array +Required: false +Default: [] +ItemsType: string ``` -[01]: https://jsonlines.org/ + +[01]: root.md#kind +[02]: get.md#resource-type-argument +[03]: get.md#resource-path-argument +[04]: https://jsonlines.org/ +[05]: get.md#resource-version-argument +[06]: get.md#adapted-content-argument +[07]: ../stdout/list.md diff --git a/docs/reference/schemas/resource/manifest/delete.md b/docs/reference/schemas/resource/manifest/delete.md index 938c4a55c..193979a49 100644 --- a/docs/reference/schemas/resource/manifest/delete.md +++ b/docs/reference/schemas/resource/manifest/delete.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'delete' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest delete property schema reference --- @@ -25,7 +25,7 @@ Defines how DSC must call the DSC Resource to delete an instance. Define this me as an alternative to handling the [`_exist`][01] property in a `set` operation, which can lead to highly complex code. If the `set` method for the resource is able to handle deleting an instance when `_exist` is `false`, set the [`handlesExist`][02] property of the set method definition to -`true` instead. +`true` instead. When this property is defined, the resource has the `delete` capability. If you define the delete method in a resource manifest, ensure that you also define the [`_exist`][01] property in the [JSON schema for the resource's properties][03]. @@ -45,8 +45,51 @@ input JSON to the resource. You can only define one JSON input argument for a co You must define the `input` property, one JSON input argument in the `args` property array, or both. +When the `args` array includes a [what-if argument](#what-if-argument), the resource has the +`deleteWhatIf` capability. DSC calls the `delete` command with the what-if argument when a user +invokes the operation in what-if mode, like with the `--what-if` option for the +[dsc resource delete][04] command, and the resource reports how it would remove the instance +without modifying the system. When the `args` array doesn't include a what-if argument, DSC +synthesizes the what-if result from the `test` operation. The `deleteWhatIf` capability was added +in DSC version 3.3.0. + ## Examples +### Example 1 - Definition with a what-if argument + +```json +"delete": { + "executable": "my_app", + "args": [ + "config", + "delete", + { "whatIfArg": "--what-if" } + ], + "input": "stdin" +} +``` + +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 two string arguments, `config` and `delete`, and a what-if argument. The value +of the `input` property indicates that the `delete` command expects its input as a JSON blob from +`stdin`. + +When a user invokes the `delete` operation normally, DSC calls the command as: + +```sh +{ ... } | my_app config delete +``` + +When a user invokes the `delete` operation in what-if mode, DSC calls the command as: + +```sh +{ ... } | my_app config delete --what-if +``` + +Because the manifest defines the what-if argument, the resource has the `deleteWhatIf` capability. + ## Required properties The `delete` definition must include these properties: @@ -69,17 +112,31 @@ 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. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. +- [What-if argument](#what-if-argument) - The argument to pass when the operation runs in what-if + mode. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments and the what-if argument, DSC passes the argument name followed by its +value as two separate arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -91,15 +148,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][05]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### 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: +JSON input to the named argument when available. -- `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, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates 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. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -115,14 +192,80 @@ ways: 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. +input JSON to the resource. You must define the `input` property, a JSON input argument in the +`args` property array, or both. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][06] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + +#### What-if argument + +Defines the argument to pass to the command when a user invokes the `delete` operation in what-if +mode. DSC only passes the named argument when the operation runs in what-if mode. When the +operation runs normally, DSC omits the argument. + +When the `args` array includes a what-if argument, the resource has the `deleteWhatIf` capability. +In what-if mode, DSC calls the `delete` command with the argument instead of synthesizing the +result from the `test` operation. The resource must not modify the system and must return a JSON +object describing the expected result. For more information about the expected output, see +[DSC resource delete operation stdout schema reference][07]. + +- `whatIfArg` (required) - The argument to pass in what-if mode, like `--what-if`. + +```yaml +Type: object +RequiredProperties: [whatIfArg] +``` + ### input The `input` property defines how to pass input to the resource. If this property isn't defined and @@ -160,7 +303,32 @@ Required: false ValidValues: [env, stdin] ``` +### requireSecurityContext + +The `requireSecurityContext` property defines the security context the resource requires for the +`delete` operation. Before invoking the command, DSC compares the current security context to this +value and raises an error if the context doesn't satisfy the requirement. The value must be one of +the following strings: + +- `current` - DSC invokes the command in any security context. This is the default behavior. +- `elevated` - DSC only invokes the command when it's running in an elevated security context, + like as an administrator on Windows or as `root` on Linux and macOS. Otherwise, DSC raises an + error. +- `restricted` - DSC only invokes the command when it's running in a non-elevated security + context. Otherwise, DSC raises an error. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + [01]: ../properties/exist.md [02]: set.md#handlesexist [03]: schema/property.md +[04]: ../../../cli/resource/delete.md +[05]: adapter.md +[06]: ../stdout/list.md#path +[07]: ../stdout/delete.md diff --git a/docs/reference/schemas/resource/manifest/export.md b/docs/reference/schemas/resource/manifest/export.md index 0a98fda5f..3f830f008 100644 --- a/docs/reference/schemas/resource/manifest/export.md +++ b/docs/reference/schemas/resource/manifest/export.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'export' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest export property schema reference --- @@ -23,7 +23,8 @@ Type: object A command-based DSC Resource that can enumerate every instance of itself with a single command should define the `export` property in its manifest. This property defines how DSC can get the -current state for every resource instance. When this property is defined, users can: +current state for every resource instance. When this property is defined, the resource has the +`export` capability and users can: - Specify an instance of the resource in the input configuration for the [dsc config export][01] command to generate an usable configuration document. @@ -34,24 +35,36 @@ current state for every resource instance. When this property is defined, users When the DSC calls the command defined by this property, the resource must return the current state of every instance as [JSON lines][05]. Each JSON Line should be an object representing the instance -and validate against the [defined resource instance schema][06]. +and validate against the [defined resource instance schema][06]. For more information about the +expected output, including the output for exporter resources, see +[DSC resource export operation stdout schema reference][07]. + +Users can provide input for the `export` operation to filter the exported instances, like with the +[--input][08] option for the `dsc resource export` command or the properties of an instance in a +configuration document. Before sending the input to the command, DSC validates it: + +1. If the manifest defines [supportsFiltering](#supportsfiltering) as `false`, DSC raises an + error. +1. If the manifest defines the [schema](#schema) property, DSC validates the input against that + schema. +1. Otherwise, if the manifest defines the [validate][09] property, DSC calls the `validate` command + to validate the input. +1. Otherwise, DSC validates the input against the resource's instance schema. DSC sends data to this command in three ways: - 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed - JSON object without spaces or newlines between the object properties. - 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment - variable for each property in the input data object, using the name and value of the property. - 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a - string representing the data as a compressed JSON object to the specified argument. +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. +input JSON to the resource. This is only appropriate for resources that don't support filtering +the exported instances. 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 +## Required properties The `export` definition must include these properties: @@ -73,17 +86,29 @@ 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. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments, DSC passes the argument name followed by its value as two separate +arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -95,15 +120,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][10]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### 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: +JSON input to the named argument when available. -- `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, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates 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. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -119,14 +164,60 @@ ways: 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. +input JSON to the resource. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][11] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + ### input The `input` property defines how to pass input to the resource. If this property isn't defined and @@ -164,9 +255,82 @@ Required: false ValidValues: [env, stdin] ``` +### requireSecurityContext + +The `requireSecurityContext` property defines the security context the resource requires for the +`export` operation. Before invoking the command, DSC compares the current security context to this +value and raises an error if the context doesn't satisfy the requirement. The value must be one of +the following strings: + +- `current` - DSC invokes the command in any security context. This is the default behavior. +- `elevated` - DSC only invokes the command when it's running in an elevated security context, + like as an administrator on Windows or as `root` on Linux and macOS. Otherwise, DSC raises an + error. +- `restricted` - DSC only invokes the command when it's running in a non-elevated security + context. Otherwise, DSC raises an error. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + +### schema + +The `schema` property defines the JSON schema that DSC uses to validate the input for the `export` +operation. Define this property when the properties the resource accepts for filtering exported +instances differ from the resource's instance schema. This property uses the same shape as the +manifest [schema][12] property. The value must be an object that defines one of the following +properties: + +- `command` - When you specify the `command` property, DSC calls the defined command to get the + JSON schema for the export input. The `command` object must define the `executable` property and + may define the `args` property, which accepts the same argument kinds as the manifest + [schema.command.args][13] property. +- `embedded` - When you specify the `embedded` property, DSC uses the defined value as the JSON + schema for the export input. + +When the manifest doesn't define this property, DSC validates the export input with the +[validate][09] command if the manifest defines it, or against the resource's instance schema +otherwise. A manifest can't define both this property and `supportsFiltering`. + +This property was added in DSC version 3.3.0. + +```yaml +Type: object +Required: false +RequiredProperties: [command | embedded] +``` + +### supportsFiltering + +The `supportsFiltering` property indicates whether the resource accepts input for the `export` +operation to filter the exported instances. When this property is `false`, DSC raises an error if +a user provides input for the `export` operation. When this property is `true` or isn't defined, +DSC validates the input and sends it to the command. + +A manifest can't define both this property and `schema`. + +This property was added in DSC version 3.3.0. + +```yaml +Type: boolean +Required: false +Default: true +``` + + [01]: ../../../cli/config/export.md [02]: ../../../cli/resource/export.md [03]: ../../../cli/resource/get.md [04]: ../../../cli/resource/get.md#-a---all [05]: https://jsonlines.org/ [06]: schema/property.md +[07]: ../stdout/export.md +[08]: ../../../cli/resource/export.md#-i---input +[09]: validate.md +[10]: adapter.md +[11]: ../stdout/list.md#path +[12]: root.md#schema-1 +[13]: schema/property.md#args diff --git a/docs/reference/schemas/resource/manifest/get.md b/docs/reference/schemas/resource/manifest/get.md index 7ffae514b..086d88b42 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: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest get property schema reference --- @@ -21,8 +21,11 @@ Type: object ## Description -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. +Nearly every command-based DSC Resource should define the `get` property in its manifest. This +property defines how DSC can get the current state of a resource instance. When a manifest doesn't +define this property, the resource doesn't have the `get` capability and DSC can't retrieve the +current state of the resource's instances or synthesize results for the `test` and `set` +operations. DSC sends data to the command in three ways: @@ -34,10 +37,13 @@ DSC sends data to the command in three ways: 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. +input JSON to the resource. This is only appropriate for resources that don't need any input to +return their current state, like `Microsoft/OSInfo`. 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. +DSC only sends input to the `get` command when the user or configuration document provides +instance properties for the operation. When there's no input, DSC omits the JSON input argument +unless the argument is defined as mandatory. ## Examples @@ -52,13 +58,13 @@ This example is from the `Microsoft/OSInfo` DSC Resource. ``` It only defines the `executable` property. When a manifest doesn't define `args`, DSC passes no -arguments to the command. When a manifest doesn't define `input`, the default behavior is to send a -JSON blob to the command over `stdin`. +arguments to the command. When a manifest doesn't define `input` or a JSON input argument, DSC +doesn't send any input to the command. With this definition, DSC calls the `get` method for this resource by running: ```sh -{ ... } | osinfo +osinfo ``` ### Example 2 - Input from stdin @@ -97,11 +103,14 @@ This example uses a JSON input argument to send the data to the command. "config", "get", { "jsonInputArg": "--input", "mandatory": true } - ], + ] } ``` -It defines the executable as `tstoy`. It defines two [string arguments](#string-arguments) and one [JSON input argument](#json-input-argument). When DSC invokes the `get` operation for this resource, it passes the JSON data to the resource as a compressed JSON string to the `--input` argument. +It defines the executable as `tstoy`. It defines two [string arguments](#string-arguments) and one +[JSON input argument](#json-input-argument). When DSC invokes the `get` operation for this +resource, it passes the JSON data to the resource as a compressed JSON string to the `--input` +argument. The combined call for this operation is: @@ -115,7 +124,36 @@ Because the `mandatory` option for the JSON input argument is set to `true`, DSC string to the argument when there's no data to send to the command. If the property wasn't defined, or was defined as `false`, DSC would omit the argument entirely when there's no data to send. -## Required Properties +### Example 4 - Adapter arguments + +This example is from the `Microsoft.Adapter/PowerShell` DSC Resource Adapter. + +```json +"get": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-ExecutionPolicy", + "Bypass", + "-Command", + "$Input | ./psDscAdapter/powershell.resource.ps1", + "Get", + { "resourceTypeArg": "-ResourceType" }, + { "resourcePathArg": "-ResourcePath", "includeQuotes": true } + ], + "input": "stdin" +} +``` + +The adapter defines a [resource type argument](#resource-type-argument) and a +[resource path argument](#resource-path-argument). When DSC invokes the adapter to get the state of +an adapted resource, it passes the adapted resource's fully qualified type name to the +`-ResourceType` argument and the path to the file that defines the adapted resource, wrapped in +double quotes, to the `-ResourcePath` argument. DSC sends the instance properties over `stdin`. + +## Required properties The `get` definition must include these properties: @@ -137,17 +175,29 @@ 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. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments, DSC passes the argument name followed by its value as two separate +arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -159,15 +209,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][01]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### 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: +JSON input to the named argument when available. -- `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, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates 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. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -183,14 +253,60 @@ ways: 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. +input JSON to the resource. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][02] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + ### input The `input` property defines how to pass input to the resource. If this property isn't defined and @@ -227,3 +343,28 @@ Type: string Required: false ValidValues: [env, stdin] ``` + +### requireSecurityContext + +The `requireSecurityContext` property defines the security context the resource requires for the +`get` operation. Before invoking the command, DSC compares the current security context to this +value and raises an error if the context doesn't satisfy the requirement. The value must be one of +the following strings: + +- `current` - DSC invokes the command in any security context. This is the default behavior. +- `elevated` - DSC only invokes the command when it's running in an elevated security context, + like as an administrator on Windows or as `root` on Linux and macOS. Otherwise, DSC raises an + error. +- `restricted` - DSC only invokes the command when it's running in a non-elevated security + context. Otherwise, DSC raises an error. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + + +[01]: adapter.md +[02]: ../stdout/list.md#path diff --git a/docs/reference/schemas/resource/manifest/resolve.md b/docs/reference/schemas/resource/manifest/resolve.md index b53f40ab1..ed278784f 100644 --- a/docs/reference/schemas/resource/manifest/resolve.md +++ b/docs/reference/schemas/resource/manifest/resolve.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'resolve' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest resolve property schema reference --- @@ -24,7 +24,8 @@ Type: object 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`. +property in the manifest root to `importer`. When this property is defined, the resource has the +`resolve` capability. DSC sends data to the command in three ways: @@ -63,17 +64,29 @@ 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. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments, DSC passes the argument name followed by its value as two separate +arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -85,16 +98,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][03]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### 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: +JSON input to the named argument when available. -- `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, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates 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. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -110,14 +142,61 @@ ways: 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. +input JSON to the resource. You must define the `input` property, a JSON input argument in the +`args` property array, or both. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][04] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + ### input The `input` property defines how to pass input to the resource. If this property isn't defined and @@ -158,3 +237,5 @@ ValidValues: [env, stdin] [01]: ../../definitions/resourceKind.md#importer-resources [02]: ./root.md#kind +[03]: adapter.md +[04]: ../stdout/list.md#path diff --git a/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md index e60920132..d173f92ad 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: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: Command-based DSC Resource manifest schema reference --- @@ -38,7 +38,6 @@ The manifest must include these properties: - [$schema](#schema) - [type](#type) - [version](#version) -- [get](#get) ## Properties @@ -77,7 +76,7 @@ For every version of the schema, there are three valid URLs: it includes additional definitions that provide contextual help and snippets that the others don't include. - This schema uses keywords that are only recognized by Visual Studio Code. While DSC can still + This schema uses keywords that are only recognized by Visual Studio Code. While DSC can still validate the document when it uses this schema, other tools may error or behave in unexpected ways. @@ -89,9 +88,33 @@ ValidValues: [ https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/resource/manifest.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/resource/manifest.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/resource/manifest.vscode.json @@ -110,9 +133,33 @@ ValidValues: [ https://aka.ms/dsc/schemas/v3/resource/manifest.json https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.3/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.3/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.3/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.2/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.2/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.2/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.1/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.1/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.1/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.0/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.0/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.0/bundled/resource/manifest.vscode.json https://aka.ms/dsc/schemas/v3.1/resource/manifest.json https://aka.ms/dsc/schemas/v3.1/bundled/resource/manifest.json https://aka.ms/dsc/schemas/v3.1/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.1.3/resource/manifest.json + https://aka.ms/dsc/schemas/v3.1.3/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.1.3/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.1.2/resource/manifest.json + https://aka.ms/dsc/schemas/v3.1.2/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.1.2/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.1.1/resource/manifest.json + https://aka.ms/dsc/schemas/v3.1.1/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.1.1/bundled/resource/manifest.vscode.json https://aka.ms/dsc/schemas/v3.1.0/resource/manifest.json https://aka.ms/dsc/schemas/v3.1.0/bundled/resource/manifest.json https://aka.ms/dsc/schemas/v3.1.0/bundled/resource/manifest.vscode.json @@ -135,30 +182,43 @@ ValidValues: [ The `type` property represents the fully qualified type name of the resource. It's used to specify the resource in configuration documents and as the value of the `--resource` flag when using the -`dsc resource *` commands. For more information about resource type names, see +`dsc resource *` commands. The type name must define an owner segment, any number of optional +namespace segments separated by periods (`.`), and a name segment separated from the preceding +segments by a forward slash (`/`), like `Microsoft.Windows/Registry`. Each segment must contain +only alphanumeric characters and underscores. For more information about resource type names, see [DSC Resource fully qualified type name schema reference][01]. ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ ``` -### version +### condition -The `version` property must be the current version of the resource as a valid semantic version -(SemVer) string. The version applies to the resource, not the software it manages. +The `condition` property defines a DSC expression that DSC evaluates during resource discovery to +decide whether the manifest is active. The value must be an expression string that returns a +boolean value, like `[not(equals(tryWhich('pwsh'), null()))]`. When the expression returns +`false`, DSC skips the manifest and doesn't include the resource in discovery results. When the +expression returns any value other than a boolean, DSC raises an error. + +Use this property to hide a resource when its dependencies aren't available on the system, like an +adapter that requires a specific shell or runtime. For more information about the available +functions, see [DSC configuration document functions reference][02] and the [tryWhich()][03] +function. ```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-]+)*))?$ +Required: false ``` -### description +### deprecationMessage -The `description` property defines a synopsis for the resource's purpose. The value for this -property must be a short string. +The `deprecationMessage` property indicates that the resource is deprecated. When a manifest +defines this property, DSC emits the message as a warning whenever a user invokes an operation for +the resource and includes the message in the output of the `dsc resource list` command. Use this +property to direct users to a replacement resource, like +`Use the 'Microsoft.Adapter/PowerShell' adapter instead.` ```yaml Type: string @@ -167,24 +227,49 @@ Required: false ### kind -The `kind` property defines how DSC should handle the resource. DSC supports several kinds -of DSC resources: `resource`, `group`, `adapter`, `importer`, and `exporter`. +The `kind` property defines how DSC should handle the resource. DSC supports several kinds of +resources: `resource`, `adapter`, `group`, `importer`, and `exporter`. When `kind` isn't defined in the resource manifest, DSC infers the value for the property. If the -`adapter` property is defined in the resource manifest, DSC infers the value of `kind` as -`adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as `resource`. -DSC can't infer whether a manifest is for a `group` or `importer` resource. +[adapter](#adapter) property is defined in the resource manifest, DSC infers the value of `kind` +as `adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as +`resource`. DSC can't infer whether a manifest is for a `group`, `importer`, or `exporter` +resource. -When defining a group resource, always explicitly define the `kind` property in the manifest as -`group`. When defining an importer resource, always explicitly define the `kind` property in the -manifest as `importer`. +When defining a group, importer, or exporter resource, always explicitly define the `kind` property +in the manifest. -For more information, see [DSC Resource kind schema reference][02]. +For more information, see [DSC Resource kind schema reference][04]. ```yaml Type: string Required: false -ValidValues: [resource, adapter, group, importer, exporter] +ValidValues: [adapter, exporter, group, importer, resource] +``` + +### version + +The `version` property must be the current version of the resource as a valid semantic version +(SemVer) string. The version applies to the resource, not the software it manages. + +For backward compatibility, DSC also accepts a date-based version in the format `YYYY-MM-DD` with +an optional prerelease suffix, like `2026-08-31-preview`. Date-based versions are deprecated. DSC +emits a warning when it discovers a manifest that defines a date-based version. + +```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-]+)*))?$ +``` + +### description + +The `description` property defines a synopsis for the resource's purpose. The value for this +property must be a short string. + +```yaml +Type: string +Required: false ``` ### tags @@ -201,39 +286,21 @@ ItemsType: string ItemsPattern: ^\w+$ ``` -### export - -The `export` property defines how to call the resource to get the current state of every instance. -When this property is defined, users can: - -- Specify an instance of the resource in the input configuration for the [dsc config export][03] - command to generate an usable configuration document. -- Specify the resource with the [dsc resource export][04] command to generate a configuration - document that defines every instance of the resource. -- Specify the resource with the [dsc resource get][05] command and the [--all][06] option to return - the current state for every instance of the resource. - -The value of this property must be an object. The object's `executable` property, defining the name -of the command to call, is mandatory. The `args` property is optional. For more -information, see [DSC Resource manifest export property schema reference][07]. - -```yaml -Type: object -Required: true -``` - ### get -The `get` property defines how to call the resource to get the current state of an instance. This -property is mandatory for all resources. +The `get` property defines how to call the resource to get the current state of an instance. +Although the schema doesn't require this property, nearly every resource should define it. When a +manifest doesn't define `get`, the resource doesn't have the `get` capability and DSC can't +retrieve the current state of the resource's instances or synthesize results for the `test` and +`set` operations. The value of this property must be an object. The object's `executable` property, defining the name -of the command to call, is mandatory. The `args` and `input` properties are optional. For more -information, see [DSC Resource manifest get property schema reference][08]. +of the command to call, is mandatory. The `args`, `input`, and `requireSecurityContext` properties +are optional. For more information, see [DSC Resource manifest get property schema reference][05]. ```yaml Type: object -Required: true +Required: false ``` ### set @@ -244,8 +311,9 @@ 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`, `implementsPretest`, and `returns` properties -are optional. For more information, see [DSC Resource manifest set property schema reference][09]. +command to call, is mandatory. The `args`, `input`, `implementsPretest`, `handlesExist`, `return`, +`requireSecurityContext`, and `whatIfReturns` properties are optional. For more information, see +[DSC Resource manifest set property schema reference][06]. ```yaml Type: object @@ -254,15 +322,26 @@ 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 `whatIf` property defines how to call the resource to indicate whether and how the `set` +operation would modify an instance without changing the system. This property uses the same schema +as the [set](#set) property. + +Defining a separate `whatIf` command is deprecated. Instead, define a [what-if argument][07] in the +`args` array of the `set` property. When the `set` definition includes a what-if argument, DSC +ignores the `whatIf` property. When the `set` definition doesn't include a what-if argument and the +manifest defines `whatIf`, DSC calls the `whatIf` command in what-if mode and emits a warning. When +the manifest defines neither, DSC synthesizes the what-if result by converting the result of the +`test` operation for the resource into a 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]. +command to call, is mandatory. The `args`, `input`, `implementsPretest`, `handlesExist`, `return`, +`requireSecurityContext`, and `whatIfReturns` properties are optional. For more information, see +[DSC Resource manifest whatIf property schema reference][08]. + +```yaml +Type: object +Required: false +``` ### test @@ -271,8 +350,65 @@ state. It also defines how to process the output from the resource for this meth property isn't defined, DSC performs a basic synthetic test for instances of the DSC Resource. The value of this property must be an object. The object's `executable` property, defining the name -of the command to call, is mandatory. The `args` `input`, and `returns` properties are optional. -For more information, see [DSC Resource manifest test property schema reference][11]. +of the command to call, is mandatory. The `args`, `input`, `return`, and `requireSecurityContext` +properties are optional. For more information, see +[DSC Resource manifest test property schema reference][09]. + +```yaml +Type: object +Required: false +``` + +### delete + +The `delete` property defines how to call the resource to remove an instance. When this property is +defined, the resource has the `delete` capability. Define this property as an alternative to +handling the [_exist][10] property in the `set` operation. If the resource's `set` command handles +removing an instance when `_exist` is `false`, define the `handlesExist` property of the `set` +method as `true` instead. + +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 `requireSecurityContext` properties +are optional. For more information, see +[DSC Resource manifest delete property schema reference][11]. + +```yaml +Type: object +Required: false +``` + +### export + +The `export` property defines how to call the resource to get the current state of every instance. +When this property is defined, the resource has the `export` capability and users can: + +- Specify an instance of the resource in the input configuration for the [dsc config export][12] + command to generate an usable configuration document. +- Specify the resource with the [dsc resource export][13] command to generate a configuration + document that defines every instance of the resource. +- Specify the resource with the [dsc resource get][14] command and the [--all][15] option to return + the current state for every instance of the resource. + +The value of this property must be an object. The object's `executable` property, defining the name +of the command to call, is mandatory. The `args`, `input`, `requireSecurityContext`, `schema`, and +`supportsFiltering` properties are optional. For more information, see +[DSC Resource manifest export property schema reference][16]. + +```yaml +Type: object +Required: false +``` + +### resolve + +The `resolve` property defines how to call an importer resource to resolve an external source into +a nested configuration document. When this property is defined, the resource has the `resolve` +capability. Define this property for [importer resources][04] and set the `kind` property to +`importer`. + +The value of this property must be an object. The object's `executable` property, defining the name +of the command to call, is mandatory. The `args` and `input` properties are optional. For more +information, see [DSC Resource manifest resolve property schema reference][17]. ```yaml Type: object @@ -281,12 +417,15 @@ Required: false ### validate -The `validate` property defines how to call a DSC Group Resource to validate its instances. This -property is mandatory for DSC Group Resources. DSC ignores this property for all other resources. +The `validate` property defines how to call the resource to validate the JSON for an instance. +When a manifest defines this property, DSC calls the command to validate instance JSON instead of +validating the JSON against the resource's instance schema. Group resources, importer resources, +and resource adapters process nested resource instances that don't share a single instance schema. +Always define this property for those resources. The value of this property must be an object. The object's `executable` property, defining the name -of the command to call, is mandatory. The `args` property is optional. For more information, see -[DSC Resource manifest validate property schema reference][12]. +of the command to call, is mandatory. The `args` and `input` properties are optional. For more +information, see [DSC Resource manifest validate property schema reference][18]. ```yaml Type: object @@ -295,12 +434,18 @@ Required: false ### adapter -When specified, the `adapter` property defines the resource as a DSC Resource Adapter. +When specified, the `adapter` property defines the resource as a DSC Resource Adapter. When the +manifest doesn't define the `kind` property, DSC infers the kind as `adapter`. -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 adapter to return the resources that the -adapter can manage. The `config` property defines how the adapter expects input. For more -information, see the [DSC Resource manifest adapter property schema reference][13]. +The value of this property must be an object. The object's `inputKind` property is mandatory and +defines how the adapter expects to receive input. The `list` property is optional and defines how to +call the adapter to return the resources that the adapter can manage. For more information, see the +[DSC Resource manifest adapter property schema reference][19]. + +```yaml +Type: object +Required: false +``` ### exitCodes @@ -313,7 +458,9 @@ Define this property as a set of key-value pairs where: exit code as `-2147024891`. - The value is a string describing the semantic meaning of that exit code for a human reader. -DSC interprets exit code `0` as a successful operation and any other exit code as an error. +DSC interprets exit code `0` as a successful operation and any other exit code as an error. When +the manifest doesn't define this property, DSC describes exit code `0` as `Success` and every other +exit code as `Error` in its messages. > [!TIP] > If you're authoring your resource manifest in yaml, be sure to wrap the exit code in single @@ -331,7 +478,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 ``` @@ -345,24 +492,49 @@ 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][14]. +DSC uses the schema to validate the input for an operation and, for resources with the `resource` +kind, the output the resource returns. When a manifest defines the [validate](#validate) property, +DSC calls that command instead of validating against the schema. When a manifest defines neither +`schema` nor `validate`, DSC raises an error when it needs to validate instance JSON for the +resource. + +For more information, see [DSC Resource manifest schema property reference][20]. ```yaml Type: object -Required: true +Required: false +``` + +### metadata + +The `metadata` property defines an arbitrary set of key-value pairs for the resource. DSC doesn't +validate or process the values in this object. Resource authors and integrating tools can use this +property to store additional information about the resource, like links to documentation or the +source repository for the resource. + +```yaml +Type: object +Required: false ``` + [01]: ../../definitions/resourceType.md -[02]: ../../definitions/resourceKind.md -[03]: ../../../cli/config/export.md -[04]: ../../../cli/resource/export.md -[05]: ../../../cli/resource/get.md -[06]: ../../../cli/resource/get.md#-a---all -[07]: export.md -[08]: get.md -[09]: set.md -[10]: whatif.md -[11]: test.md -[12]: validate.md -[13]: adapter.md -[14]: schema/property.md +[02]: ../../config/functions/overview.md +[03]: ../../config/functions/tryWhich.md +[04]: ../../definitions/resourceKind.md +[05]: get.md +[06]: set.md +[07]: set.md#what-if-argument +[08]: whatif.md +[09]: test.md +[10]: ../properties/exist.md +[11]: delete.md +[12]: ../../../cli/config/export.md +[13]: ../../../cli/resource/export.md +[14]: ../../../cli/resource/get.md +[15]: ../../../cli/resource/get.md#-a---all +[16]: export.md +[17]: resolve.md +[18]: validate.md +[19]: adapter.md +[20]: schema/property.md diff --git a/docs/reference/schemas/resource/manifest/schema/embedded.md b/docs/reference/schemas/resource/manifest/schema/embedded.md index 7876edc70..e85b2b257 100644 --- a/docs/reference/schemas/resource/manifest/schema/embedded.md +++ b/docs/reference/schemas/resource/manifest/schema/embedded.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the embedded instance schema in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest embedded schema reference --- @@ -25,7 +25,7 @@ The `embedded` subproperty defines a full JSON schema for a DSC Resource's insta JSON schema to validate every instance of the resource before calling the resource's commands and after receiving an instance as output from the resource. -Embedded JSON schemas are also used by integrating and authoring tools like Visual Studio Code to +Embedded JSON schemas are also used by integrating and authoring tools like Visual Studio Code to validate resource instances and provide IntelliSense. ## Required keywords @@ -110,7 +110,7 @@ If defined, this property must be a reference to the schema for the canonical pr } ``` -For more information, see [DSC Resource _ensure property schema][01]. +For more information, see [DSC Resource _exist property schema][01]. #### _inDesiredState @@ -144,7 +144,8 @@ If defined, this property must be a reference to the schema for the canonical pr For more information, see [DSC Resource _purge property schema][04]. -[01]: ../../properties/ensure.md + +[01]: ../../properties/exist.md [02]: ../test.md [03]: ../../properties/inDesiredState.md [04]: ../../properties/purge.md diff --git a/docs/reference/schemas/resource/manifest/schema/property.md b/docs/reference/schemas/resource/manifest/schema/property.md index 8a0bb87f2..a54cc4a06 100644 --- a/docs/reference/schemas/resource/manifest/schema/property.md +++ b/docs/reference/schemas/resource/manifest/schema/property.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'schema' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest schema property schema reference --- @@ -21,8 +21,12 @@ Type: object ## Description -Every command-based DSC Resource must define the `schema` property in its manifest. This property -defines how DSC can get the JSON schema it needs to validate instances of the resource. +Every command-based DSC Resource that doesn't define the [validate][01] property should define the +`schema` property in its manifest. This property defines how DSC can get the JSON schema it needs +to validate instances of the resource. DSC validates the input for an operation against the schema +before invoking the resource and, for resources with the `resource` [kind][02], validates the +output the resource returns. When a manifest defines neither `schema` nor `validate`, DSC raises an +error when it needs to validate an instance of the resource. The JSON schema can be defined dynamically with the [command](#command) property or statically with the [embedded](#embedded) property. @@ -88,7 +92,31 @@ DSC uses to validate an instance of the resource. } ``` -## Required Properties +### Example 3 - Get JSON schema for an adapted resource + +This example defines a schema command for a resource adapter that operates on a single adapted +resource at a time. DSC passes the type name and version of the adapted resource to the command. + +```json +"schema": { + "command": { + "executable": "my_adapter", + "args": [ + "schema", + { "resourceTypeArg": "--type" }, + { "resourceVersionArg": "--version" } + ] + } +} +``` + +When DSC needs the schema for the adapted resource `Contoso/Example` version `1.0.0`, it runs: + +```sh +my_adapter schema --type Contoso/Example --version 1.0.0 +``` + +## Required properties The `schema` definition must include exactly one of these properties: @@ -107,6 +135,9 @@ schema to a publicly available URI that matches the `$id` property of the instan enables authoring tools and other integrating applications to validate instances without running the command locally. +For more information about the expected output, see +[DSC resource schema command stdout schema reference][03]. + ```yaml Type: object RequiredProperties: [executable] @@ -126,22 +157,77 @@ Required: true #### args -The `args` property defines an array of strings to pass as arguments to the command. DSC passes the -arguments to the command in the order they're specified. +The `args` property defines the list of arguments to pass to the command. DSC passes the arguments +to the command in the order they're specified. Each item in the array must be a string or an object +that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `schema`. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. + +For every argument kind except string arguments, DSC passes the argument name followed by its value +as two separate arguments. + +```yaml +Type: array +Required: false +Default: [] +ItemsType: [string, object] +``` + +##### String arguments + +Any item in the argument array can be a string representing a static argument to pass to the +command, like `schema` or `--format`. + +```yaml +Type: string +``` + +##### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that returns the schema for a single adapted resource. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `--type`. ```yaml -Type: array -Required: false -Default: [] +Type: object +RequiredProperties: [resourceTypeArg] +``` + +##### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `--version`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] ``` ### embedded The `embedded` property defines the full JSON schema for DSC to validate instances of the DSC Resource. The value for this property must be a valid JSON schema that defines the `$schema`, -`type`, and `properties` keywords. +`type`, and `properties` keywords. For more information, see +[DSC Resource manifest embedded schema reference][04]. ```yaml Type: object MinimumPropertyCount: 1 ``` + + +[01]: ../validate.md +[02]: ../root.md#kind +[03]: ../../stdout/schema.md +[04]: embedded.md diff --git a/docs/reference/schemas/resource/manifest/set.md b/docs/reference/schemas/resource/manifest/set.md index 7a0f9e4a4..3ca90392b 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: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest set property schema reference --- @@ -22,26 +22,34 @@ Type: object ## Description To manage an instance with DSC, a DSC Resource must define the `set` property in its manifest. This -property defines how DSC can enforce the current state of an instance. +property defines how DSC can enforce the current state of an instance. When this property is +defined, the resource has the `set` capability. When this property isn't defined, DSC can only get the current state of instances and test whether they're in the desired state. DSC can't enforce desired state for the resource. DSC sends data to the command in three ways: - 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed - JSON object without spaces or newlines between the object properties. - 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment - variable for each property in the input data object, using the name and value of the property. - 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a - string representing the data as a compressed JSON object to the specified argument. +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. +desired state 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. +When the `args` array includes a [what-if argument](#what-if-argument), the resource has the +`setWhatIf` capability. DSC calls the `set` command with the what-if argument when a user invokes +the operation in what-if mode, like with the [--what-if][01] option for the `dsc config set` +command, and the resource reports how it would change the instance without modifying the system. +When the `args` array doesn't include a what-if argument, DSC synthesizes the what-if result from +the `test` operation, unless the manifest defines the deprecated [whatIf][02] property. + ## Examples ### Example 1 - Full definition @@ -82,7 +90,39 @@ The manifest defines `return` as `state`, indicating that it only returns the fi 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 enforced, if any. -## Required Properties +### Example 2 - What-if argument + +This example defines a what-if argument so that the resource can report the expected result of the +`set` operation without changing the system. + +```json +"set": { + "executable": "my_app", + "args": [ + "config", + "set", + { "whatIfArg": "--what-if" } + ], + "input": "stdin", + "return": "state" +} +``` + +When a user invokes the `set` operation normally, DSC calls the command as: + +```sh +{ ... } | my_app config set +``` + +When a user invokes the `set` operation in what-if mode, DSC calls the command as: + +```sh +{ ... } | my_app config set --what-if +``` + +Because the manifest defines the what-if argument, the resource has the `setWhatIf` capability. + +## Required properties The `set` definition must include these properties: @@ -104,17 +144,31 @@ 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. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. +- [What-if argument](#what-if-argument) - The argument to pass when the operation runs in what-if + mode. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments and the what-if argument, DSC passes the argument name followed by its +value as two separate arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -126,15 +180,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][03]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### 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: +JSON input to the named argument when available. -- `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, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates 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. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -150,14 +224,81 @@ ways: 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. +input JSON to the resource. You must define the `input` property, a JSON input argument in the +`args` property array, or both. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][04] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + +#### What-if argument + +Defines the argument to pass to the command when a user invokes the `set` operation in what-if +mode, like with the [--what-if][01] option for the `dsc config set` command. DSC only passes the +named argument when the operation runs in what-if mode. When the operation runs normally, DSC omits +the argument. + +When the `args` array includes a what-if argument, the resource has the `setWhatIf` capability. +In what-if mode, DSC calls the `set` command with the argument instead of synthesizing the result +from the `test` operation. The resource must return the expected result of the operation without +changing the system. For more information about the expected output, see +[DSC resource what-if operation stdout schema reference][05]. + +- `whatIfArg` (required) - The argument to pass in what-if mode, like `--what-if`. + +```yaml +Type: object +RequiredProperties: [whatIfArg] +``` + ### input The `input` property defines how to pass input to the resource. If this property isn't defined and @@ -216,24 +357,30 @@ Default: false ### handlesExist The `handlesExist` property defines whether the resource has built-in handling for the -[_exist][01] property in the `set` operation. The default value is `false`. +[_exist][06] property in the `set` operation. The default value is `false`. Set this property to `true` when the resource meets the following implementation requirements: -- The resource's [instance schema][02] defines the `_exist` property as a valid instance property. +- The resource's [instance schema][07] defines the `_exist` property as a valid instance property. - The resource's `set` command handles creating, updating, and deleting an instance based on the current state of the instance and the value of the `_exist` property in the desired state. -When this property is set to `true`, the resource indicates that it has the [SetHandlesExist][03] -[capability][04]. When processing resources with the `SetHandlesExist` capability in a +When this property is set to `true`, the resource indicates that it has the `setHandlesExist` +[capability][08]. When processing resources with the `setHandlesExist` capability in a configuration, DSC calls the `set` operation for the resource when an instance defines `_exist` as -`false`. Without this capability, a resource must define the [delete][05] operation to support +`false`. Without this capability, a resource must define the [delete][09] 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`. +```yaml +Type: boolean +Required: false +Default: false +``` + ### return The `return` property defines how DSC should process the output for this method. The value of this @@ -244,18 +391,70 @@ property must be one of the following strings: - `stateAndDiff` - Indicates that the resource returns the instance's final state and an array of property names that the resource modified. -The default value is `state`. +When this property isn't defined, DSC doesn't expect the resource to return any output for the +`set` operation. Instead, DSC invokes the `get` operation for the resource after the `set` +operation concludes and compares the result to the state of the instance before the operation to +determine which properties the operation changed. For more information, see +[DSC resource set operation stdout schema reference][10]. + +```yaml +Type: string +Required: false +ValidValues: [state, stateAndDiff] +``` + +### requireSecurityContext + +The `requireSecurityContext` property defines the security context the resource requires for the +`set` operation. Before invoking the command, DSC compares the current security context to this +value and raises an error if the context doesn't satisfy the requirement. The value must be one of +the following strings: + +- `current` - DSC invokes the command in any security context. This is the default behavior. +- `elevated` - DSC only invokes the command when it's running in an elevated security context, + like as an administrator on Windows or as `root` on Linux and macOS. Otherwise, DSC raises an + error. +- `restricted` - DSC only invokes the command when it's running in a non-elevated security + context. Otherwise, DSC raises an error. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + +### whatIfReturns + +The `whatIfReturns` property defines how DSC should process the output for this method when a user +invokes the `set` operation in what-if mode. When this property is defined, it overrides the +[return](#return) property during what-if execution. When this property isn't defined, DSC +processes the output in what-if mode the same way it processes the output for an actual `set` +operation. + +Define this property when the resource returns differently shaped data in what-if mode than it +returns for an actual `set` operation. The value must be one of the same strings as the `return` +property: + +- `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 would modify. ```yaml Type: string Required: false -Default: state ValidValues: [state, stateAndDiff] ``` - -[01]: ../properties/exist.md -[02]: ./root.md#schema-1 -[03]: ../../outputs/resource/list.md#capability-sethandlesexist -[04]: ../../outputs/resource/list.md#capabilities -[05]: ./delete.md + +[01]: ../../../cli/config/set.md#-w---what-if +[02]: whatif.md +[03]: adapter.md +[04]: ../stdout/list.md#path +[05]: ../stdout/whatIf.md +[06]: ../properties/exist.md +[07]: ./root.md#schema-1 +[08]: ../../definitions/resourceCapabilities.md +[09]: ./delete.md +[10]: ../stdout/set.md diff --git a/docs/reference/schemas/resource/manifest/test.md b/docs/reference/schemas/resource/manifest/test.md index 7305b3459..9519e4d3f 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: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest test property schema reference --- @@ -23,7 +23,8 @@ Type: object If a DSC Resource implements its own logic for determining whether an instance is in the desired state, it must define the `test` property in its manifest. This property defines how DSC can call -the resource to test whether an instance is in the desired state. +the resource to test whether an instance is in the desired state. When this property is defined, +the resource has the `test` capability. When this property isn't defined, DSC uses a synthetic test method for the resource. The synthetic test method: @@ -44,15 +45,15 @@ For resources with properties that can't be evaluated by equivalency alone, alwa 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. +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. +desired state 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. @@ -90,7 +91,7 @@ Combined with the value for `executable`, DSC calls the `test` method for this r The manifest defines `return` as `state`, indicating that it only returns the actual state of the resource when the `test` method runs. -## Required Properties +## Required properties The `test` definition must include these properties: @@ -112,17 +113,29 @@ 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. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments, DSC passes the argument name followed by its value as two separate +arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -134,15 +147,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][01]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### 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: +JSON input to the named argument when available. -- `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, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates 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. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -158,18 +191,66 @@ ways: 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. +input JSON to the resource. You must define the `input` property, a JSON input argument in the +`args` property array, or both. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][02] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + ### input -The `input` property defines how to pass input to the resource. If this property isn't defined, DSC -doesn't send any input to the resource when invoking the `test` operation. +The `input` property defines how to pass input to the resource. If this property isn't defined and +the definition doesn't define a [JSON input argument](#json-input-argument), DSC doesn't send any +input to the resource when invoking the `test` operation. The value of this property must be one of the following strings: @@ -207,15 +288,46 @@ ValidValues: [env, stdin] 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 actual state. +- `state` - Indicates that the resource returns only the instance's actual state, including the + [_inDesiredState][03] canonical property. - `stateAndDiff` - Indicates that the resource returns the instance's actual state and an array of property names that are out of the desired state. -The default value is `state`. +When this property isn't defined, DSC ignores any output from the `test` command. Instead, DSC +invokes the `get` operation for the resource after the `test` command completes and compares each +property of the desired state to the actual state to determine whether the instance is in the +desired state. Always define this property when the resource returns its own test result. For more +information, see [DSC resource test operation stdout schema reference][04]. ```yaml Type: string Required: false -Default: state ValidValues: [state, stateAndDiff] ``` + +### requireSecurityContext + +The `requireSecurityContext` property defines the security context the resource requires for the +`test` operation. Before invoking the command, DSC compares the current security context to this +value and raises an error if the context doesn't satisfy the requirement. The value must be one of +the following strings: + +- `current` - DSC invokes the command in any security context. This is the default behavior. +- `elevated` - DSC only invokes the command when it's running in an elevated security context, + like as an administrator on Windows or as `root` on Linux and macOS. Otherwise, DSC raises an + error. +- `restricted` - DSC only invokes the command when it's running in a non-elevated security + context. Otherwise, DSC raises an error. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + + +[01]: adapter.md +[02]: ../stdout/list.md#path +[03]: ../properties/inDesiredState.md +[04]: ../stdout/test.md diff --git a/docs/reference/schemas/resource/manifest/validate.md b/docs/reference/schemas/resource/manifest/validate.md index 449305cb4..ca1c8ef3b 100644 --- a/docs/reference/schemas/resource/manifest/validate.md +++ b/docs/reference/schemas/resource/manifest/validate.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'validate' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest validate property schema reference --- @@ -9,7 +9,7 @@ title: DSC Resource manifest validate property schema reference ## Synopsis -Indicates how to call a group resource to test whether nested instances are valid. +Indicates how to call a resource to test whether an instance is valid. ## Metadata @@ -21,23 +21,28 @@ Type: object ## Description -DSC Group Resources must define the `validate` property in their DSC Resource manifest. This -property defines how DSC can call the group resource to test whether instances in the group -have valid definitions. +The `validate` property defines how DSC can call a resource to test whether the JSON for an +instance is valid. When a manifest defines this property, DSC calls the command whenever it needs +to validate instance JSON for the resource instead of validating the JSON against the resource's +[instance schema][01]. DSC validates the input for an operation before invoking the resource and, +for resources with the `resource` [kind][02], the output the resource returns. -Always define the `validate` property for group resources in the DSC Resource manifest. +Group resources, importer resources, and resource adapters process nested resource instances that +don't share a single instance schema. Always define the `validate` property for these resources. +For more information about the expected output, see +[DSC resource validate operation stdout schema reference][03]. DSC sends data to the command in three ways: - 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed - JSON object without spaces or newlines between the object properties. - 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment - variable for each property in the input data object, using the name and value of the property. - 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a - string representing the data as a compressed JSON object to the specified argument. +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. +instance 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. @@ -46,28 +51,32 @@ both. ### Example 1 - Full definition -This example is from the `DSC/AssertionGroup` DSC Group Resource. +This example is from the `Microsoft.DSC/Group` DSC Group Resource. ```json "validate": { "executable": "dsc", "args": [ + "--trace-format", + "pass-through", "config", - "validate" + "validate", + { "jsonInputArg": "--input", "mandatory": true } ] } ``` -It defines the executable as `dsc` with the arguments `config` and `validate`. The `validate` -method always sends the method's input as a JSON blob over `stdin`. +It defines the executable as `dsc` with four string arguments and a +[JSON input argument](#json-input-argument). DSC passes the instance JSON to the `--input` +argument as a compressed JSON string. With this definition, DSC calls the `validate` method for this DSC Group Resource by running: ```sh -{ ... } | dsc config validate +dsc --trace-format pass-through config validate --input "{ ... }" ``` -## Required Properties +## Required properties The `validate` definition must include these properties: @@ -89,17 +98,29 @@ 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. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments, DSC passes the argument name followed by its value as two separate +arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -111,15 +132,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][04]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### 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: +JSON input to the named argument when available. -- `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, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates 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. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -135,18 +176,66 @@ ways: 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. +input JSON to the resource. You must define the `input` property, a JSON input argument in the +`args` property array, or both. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][05] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + ### input -The `input` property defines how to pass input to the resource. If this property isn't defined, DSC -doesn't send any input to the resource when invoking the `validate` operation. +The `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 `validate` operation. The value of this property must be one of the following strings: @@ -178,3 +267,10 @@ Type: string Required: false ValidValues: [env, stdin] ``` + + +[01]: schema/property.md +[02]: root.md#kind +[03]: ../stdout/validate.md +[04]: adapter.md +[05]: ../stdout/list.md#path diff --git a/docs/reference/schemas/resource/manifest/whatif.md b/docs/reference/schemas/resource/manifest/whatif.md index 404806d31..f6528b1a9 100644 --- a/docs/reference/schemas/resource/manifest/whatif.md +++ b/docs/reference/schemas/resource/manifest/whatif.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'whatIf' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest whatIf property schema reference --- @@ -26,12 +26,22 @@ the [--what-if][02] option to see whether and how resources will change system s 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: +The `whatIf` property has the same schema and shape as the [set][03] property. Every property that +you can define for the `set` method is valid for the `whatIf` method. + +> [!IMPORTANT] +> Defining a separate `whatIf` command is deprecated. Instead, define a [what-if argument][04] in +> the `args` array of the `set` property. When the `set` definition includes a what-if argument, +> DSC ignores the `whatIf` property. When the `set` definition doesn't include a what-if argument +> and the manifest defines `whatIf`, DSC calls the `whatIf` command in what-if mode and emits a +> warning. + +When the manifest defines neither a what-if argument nor the `whatIf` property, 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 @@ -44,21 +54,21 @@ sufficient information to the user: 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. +If your resource uses parameters or returns read-only properties from a `set` operation, define a +what-if argument for the `set` 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. +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. +desired state 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. @@ -68,15 +78,15 @@ both. ### Example 1 - Full definition ```json -"set": { +"whatIf": { "executable": "my_app", "args": [ "config", "set", "--what-if" ], - "input": "stdin", - "return": "state" + "input": "stdin", + "return": "state" } ``` @@ -97,7 +107,29 @@ The manifest defines `return` as `state`, indicating that it only returns the ex 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 +### Example 2 - Equivalent definition with a what-if argument + +This example defines the same behavior as the previous example with a what-if argument for the +`set` method instead of a separate `whatIf` definition. This is the recommended approach. + +```json +"set": { + "executable": "my_app", + "args": [ + "config", + "set", + { "whatIfArg": "--what-if" } + ], + "input": "stdin", + "return": "state" +} +``` + +DSC only passes the `--what-if` argument to the command when a user invokes the `set` operation in +what-if mode. Because the manifest defines the what-if argument, the resource has the `setWhatIf` +capability. + +## Required properties The `whatIf` definition must include these properties: @@ -119,17 +151,31 @@ 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. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. +- [What-if argument](#what-if-argument) - The argument to pass when the operation runs in what-if + mode. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments and the what-if argument, DSC passes the argument name followed by its +value as two separate arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -141,16 +187,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][05]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### 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: +JSON input to the named argument when available. -- `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, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates 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. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -166,14 +231,75 @@ ways: 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. +input JSON to the resource. You must define the `input` property, a JSON input argument in the +`args` property array, or both. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][06] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + +#### What-if argument + +Defines the argument to pass to the command when the operation runs in what-if mode. DSC always +invokes the `whatIf` command in what-if mode, so DSC always passes the named argument to the +command. Define the what-if argument for the [set method][04] instead of the `whatIf` method to +use a single command for both modes. + +- `whatIfArg` (required) - The argument to pass in what-if mode, like `--what-if`. + +```yaml +Type: object +RequiredProperties: [whatIfArg] +``` + ### input The `input` property defines how to pass input to the resource. If this property isn't defined and @@ -233,26 +359,32 @@ 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 +[_exist][07] property in the `set` operation. The default value is `false`. In most cases, this +value should be set the same as the `handlesExist` 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 [instance schema][08] 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 +When this property is set to `true`, the resource indicates that it has the `setHandlesExist` +[capability][09]. 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 +`false`. Without this capability, a resource must define the [delete][10] 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`. +```yaml +Type: boolean +Required: false +Default: false +``` + ### return The `return` property defines how DSC should process the output for this method. The value of this @@ -261,23 +393,67 @@ 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. + array of property names that the resource would modify. -The default value is `state`. +When this property isn't defined, DSC doesn't expect the resource to return any output. Instead, +DSC invokes the `get` operation for the resource after the command concludes and compares the +result to the state of the instance before the operation. For more information, see +[DSC resource what-if operation stdout schema reference][11]. + +```yaml +Type: string +Required: false +ValidValues: [state, stateAndDiff] +``` + +### requireSecurityContext + +The `requireSecurityContext` property defines the security context the resource requires for the +`whatIf` operation. Before invoking the command, DSC compares the current security context to this +value and raises an error if the context doesn't satisfy the requirement. The value must be one of +the following strings: + +- `current` - DSC invokes the command in any security context. This is the default behavior. +- `elevated` - DSC only invokes the command when it's running in an elevated security context, + like as an administrator on Windows or as `root` on Linux and macOS. Otherwise, DSC raises an + error. +- `restricted` - DSC only invokes the command when it's running in a non-elevated security + context. Otherwise, DSC raises an error. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + +### whatIfReturns + +The `whatIfReturns` property defines how DSC should process the output for this method in what-if +mode. Because DSC always invokes the `whatIf` command in what-if mode, this property overrides the +[return](#return) property whenever it's defined. The value must be one of the same strings as the +`return` property: + +- `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 would modify. ```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 +[04]: ./set.md#what-if-argument +[05]: adapter.md +[06]: ../stdout/list.md#path +[07]: ../properties/exist.md +[08]: ./root.md#schema-1 +[09]: ../../definitions/resourceCapabilities.md +[10]: ./delete.md +[11]: ../stdout/whatIf.md diff --git a/docs/reference/schemas/resource/properties/ensure.md b/docs/reference/schemas/resource/properties/ensure.md index 97085e755..8979e7497 100644 --- a/docs/reference/schemas/resource/properties/ensure.md +++ b/docs/reference/schemas/resource/properties/ensure.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_ensure' well-known DSC Resource property. -ms.date: 01/17/2024 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource _ensure property schema --- @@ -26,6 +26,10 @@ ValidValues: [Absent, Present] > Starting with DSC v3.0.0-alpha.4 and schema version `2023/10` this well-known property is removed > from the schema. It's replaced by the [_exist][01] property. Microsoft recommends migrating > resources to use the `_exist` keyword instead. +> +> This page describes a legacy property and is retained for reference only. No released version +> of DSC v3 recognizes `_ensure` as a canonical property, DSC doesn't publish a schema for it under +> the `v3` schema folders, and the [canonical properties overview][02] doesn't list it. The `_ensure` property indicates that the resource can enforce whether instances exist using the shared present and absent semantics. @@ -60,4 +64,6 @@ specifically a file, or exists as a symlink. In that case, the resource would de } ``` + [01]: exist.md +[02]: overview.md diff --git a/docs/reference/schemas/resource/properties/exist.md b/docs/reference/schemas/resource/properties/exist.md index 1bd6c29f9..afa1c4ba0 100644 --- a/docs/reference/schemas/resource/properties/exist.md +++ b/docs/reference/schemas/resource/properties/exist.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_exist' canonical DSC Resource property. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource _exist property schema --- @@ -47,5 +47,3 @@ snippet: "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/exist.json" } ``` - - diff --git a/docs/reference/schemas/resource/properties/inDesiredState.md b/docs/reference/schemas/resource/properties/inDesiredState.md index 71a17ba94..9a0d927c6 100644 --- a/docs/reference/schemas/resource/properties/inDesiredState.md +++ b/docs/reference/schemas/resource/properties/inDesiredState.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_inDesiredState' canonical DSC Resource property. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource _inDesiredState property schema --- @@ -47,7 +47,6 @@ snippet: } ``` - - + [01]: ../manifest/root.md [02]: ../manifest/test.md diff --git a/docs/reference/schemas/resource/properties/overview.md b/docs/reference/schemas/resource/properties/overview.md index aad231983..3f18f7ea5 100644 --- a/docs/reference/schemas/resource/properties/overview.md +++ b/docs/reference/schemas/resource/properties/overview.md @@ -2,7 +2,7 @@ description: >- Information about the list of canonical DSC Resource properties, including their purpose and how to add them to a resource's manifest. -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC canonical properties --- @@ -38,8 +38,29 @@ DSC. For more information, see [DSC Resource _purge property schema][05]. +## _restartRequired + +The read-only `_restartRequired` property indicates that the machine, specific services, or +specific processes need to be restarted after the resource enforces the desired state. When a +resource includes this property in the output of a set operation, DSC records the restart +requirements in the execution information for the operation and makes them available to the +[restartRequired()][06] configuration function. + +The value of this property must be an array of objects. Each object defines exactly one of the +following properties: + +- `system` - A string describing why the system needs to be restarted. +- `service` - The name of a service that needs to be restarted. +- `process` - An object with the `name` and `id` properties identifying a process that needs to be + restarted. + +This property replaces the `_rebootRequested` property, which earlier schemas defined but DSC +never processed. + + [01]: exist.md [02]: ../manifest/test.md [03]: ../manifest/root.md [04]: inDesiredState.md [05]: purge.md +[06]: ../../config/functions/restartRequired.md diff --git a/docs/reference/schemas/resource/properties/purge.md b/docs/reference/schemas/resource/properties/purge.md index e783b5a69..97363e1f7 100644 --- a/docs/reference/schemas/resource/properties/purge.md +++ b/docs/reference/schemas/resource/properties/purge.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_purge' canonical DSC Resource property. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource _purge property schema --- @@ -47,5 +47,3 @@ snippet: "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/purge.json" } ``` - - diff --git a/docs/reference/schemas/resource/stdout/delete.md b/docs/reference/schemas/resource/stdout/delete.md index 86e1c25b4..1a0ca13c4 100644 --- a/docs/reference/schemas/resource/stdout/delete.md +++ b/docs/reference/schemas/resource/stdout/delete.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the delete resource operation -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource delete operation stdout schema reference --- @@ -9,18 +9,86 @@ title: DSC resource delete operation stdout schema reference ## Synopsis -DSC doesn't expect the **Delete** operation for a resource to return any JSON to stdout. +Defines the JSON DSC expects a resource to emit to stdout for the **Delete** operation. ## Metadata ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/delete.json -Type: 'null' +Type: ['null', object] ``` ## Description -DSC resources that implement the **Delete** operation shouldn't emit any data to stdout. DSC -doesn't expect any output for the **Delete** operation and ignores any data emitted to stdout when -invoking the operation. +DSC expects different output from the command resource depending on whether the user invokes the +**Delete** operation in what-if mode: + +- For an actual **Delete** operation, DSC doesn't expect the resource to return any JSON to stdout + and ignores any data emitted to stdout. +- For a **Delete** operation in what-if mode, when the resource defines a [what-if argument][01] + for the `delete` method, DSC expects the resource to emit a JSON object to stdout describing the + expected result of the operation. + +## Null output + +DSC resources that implement the **Delete** operation shouldn't emit any data to stdout for an +actual **Delete** operation. DSC doesn't expect any output for the operation and ignores any data +emitted to stdout when invoking the operation. + +```yaml +Type: 'null' +``` + +## What-if output + +When a resource defines a [what-if argument][01] for the `delete` method, the resource has the +`deleteWhatIf` capability. When a user invokes the **Delete** operation in what-if mode, DSC calls +the `delete` command with the what-if argument and expects the resource to emit a single JSON +object to stdout without modifying the system. DSC returns this object as the result of the +operation. The `deleteWhatIf` capability was added in DSC version 3.3.0. + +When a resource doesn't define a what-if argument for the `delete` method, DSC synthesizes the +what-if result from the **Test** operation and doesn't invoke the `delete` command. + +The object may be empty. DSC ignores any properties of the object other than `_metadata`. + +```yaml +Type: object +``` + +### _metadata + +Defines metadata for the what-if result. When defined, this property must be an object that only +defines the `whatIf` property. + +```yaml +Type: object +Required: false +``` + +#### whatIf + +Describes how the resource would change the system when the user invokes the **Delete** operation +without what-if mode. The value can be any valid JSON value, like a string describing the change or +an object representing the instance that the resource would remove. + +```yaml +Type: any +Required: false +``` + +For example, a resource might emit the following object in what-if mode: + +```json +{ + "_metadata": { + "whatIf": { + "message": "Would remove the registry key HKCU\\Example" + } + } +} +``` + + +[01]: ../manifest/delete.md#what-if-argument diff --git a/docs/reference/schemas/resource/stdout/list.md b/docs/reference/schemas/resource/stdout/list.md index f7175a8b6..3d568807a 100644 --- a/docs/reference/schemas/resource/stdout/list.md +++ b/docs/reference/schemas/resource/stdout/list.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the list resource operation -ms.date: 07/29/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource list operation stdout schema reference --- @@ -23,21 +23,28 @@ Type: object ## Description Defines the representation of an adapted resource in DSC. DSC expects every JSON Line emitted to -stdout for the **List** operation to adhere to this schema. +stdout for the **List** operation to adhere to this schema. DSC invokes the **List** operation for +a resource adapter with the command defined by the [adapter.list][01] property in the adapter's +manifest. + +This schema is the same schema DSC uses to represent every discovered resource, including the +output of the [dsc resource list][02] command. DSC parses each JSON Line independently. When a line +doesn't adhere to this schema, DSC logs a warning and skips the line. When a line doesn't define +the [requireAdapter](#requireadapter) property, DSC logs a warning and skips the adapted resource. DSC includes the following adapter resources: -- [Microsoft.DSC/PowerShell][01] run PowerShell and enables you to use PowerShell DSC (PSDSC) -resources implemented as PowerShell classes in DSC. -- [Microsoft.Windows/WindowsPowerShell][02] runs Windows PowerShell and enables you to use any -available PSDSC resources in DSC. This adapter is only available when you install DSC on -Windows. -- [Microsoft.Windows/WMI][03] enables you to use WMI classes as resources in DSC. This adapter is -only available when you install DSC on Windows. +- [Microsoft.DSC/PowerShell][03] run PowerShell and enables you to use PowerShell DSC (PSDSC) + resources implemented as PowerShell classes in DSC. +- [Microsoft.Windows/WindowsPowerShell][04] runs Windows PowerShell and enables you to use any + available PSDSC resources in DSC. This adapter is only available when you install DSC on + Windows. +- [Microsoft.Windows/WMI][05] enables you to use WMI classes as resources in DSC. This adapter is + only available when you install DSC on Windows. -## Required Properties +## Required properties -The output for the `discover` operation must include these properties: +The output for the **List** operation must include these properties: - [type](#type) - [kind](#kind) @@ -45,42 +52,43 @@ The output for the `discover` operation must include these properties: - [capabilities](#capabilities) - [path](#path) - [directory](#directory) -- [implementedAs](#implementedas) -- [properties](#properties-1) - [requireAdapter](#requireadapter) ## Properties ### type -The `type` property represents the fully qualified type name of the resource. It's used to specify -the resource in configuration documents and as the value of the `--resource` flag when using the -`dsc resource *` commands. For more information about resource type names, see -[DSC Resource fully qualified type name schema reference][04]. +The `type` property represents the fully qualified type name of the adapted resource. It's used to +specify the resource in configuration documents and as the value of the `--resource` flag when +using the `dsc resource *` commands. For more information about resource type names, see +[DSC Resource fully qualified type name schema reference][06]. ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ ``` ### kind The `kind` property defines how DSC should handle the adapted resource. DSC supports several kinds -of resources: `resource`, `group`, `adapter`, `importer`, and `exporter`. +of resources: `resource`, `adapter`, `group`, `importer`, and `exporter`. Adapters typically +report every adapted resource with the `resource` kind. -For more information, see [DSC resource kinds][05]. +For more information, see [DSC resource kinds][07]. ```yaml Type: string -Required: false -ValidValues: [resource, adapter, group, importer, exporter] +Required: true +ValidValues: [adapter, exporter, group, importer, resource] ``` ### version The `version` property represents the current version of the adapted resource as a valid semantic version (SemVer) string. The version applies to the adapted resource, not the software it manages. +DSC also accepts a deprecated date-based version in the format `YYYY-MM-DD` with an optional +prerelease suffix. ```yaml Type: string @@ -99,14 +107,18 @@ DSC resources may have the following capabilities: - `get` - The resource can retrieve the current state of an instance. - `set` - The resource can enforce the desired state for an instance. - `setHandlesExist` - The resource handles deleting an instance during a **Set** operation. -- `whatIf` - The resource can report how it would change state for an instance during a **Set** operation. +- `setWhatIf` - The resource can report how it would change state for an instance during a **Set** + operation without modifying the system. This capability was added in DSC version 3.3.0. Through + DSC version 3.2, this capability was named `whatIf`. - `test` - The resource implements the **Test** operation and doesn't rely on synthetic testing. - `delete` - The resource can remove an instance. +- `deleteWhatIf` - The resource can report how it would remove an instance during a **Delete** + operation without modifying the system. This capability was added in DSC version 3.3.0. - `export` - The resource can enumerate every instance. - `resolve` - The resource can resolve nested instances from an external source. -For more information about resource capabilities, see [DSC resource capabilities][06]. For more -information about the operations you can invoke for a resource, see [DSC resource operations][07]. +For more information about resource capabilities, see [DSC resource capabilities][08]. For more +information about the operations you can invoke for a resource, see [DSC resource operations][09]. ```yaml Type: array @@ -117,23 +129,46 @@ ItemsValidValues: [ get, set, setHandlesExist, - whatIf, + setWhatIf, test, delete, + deleteWhatIf, export, resolve ] ``` +### deprecationMessage + +Indicates that the adapted resource is deprecated. When defined, DSC emits the message as a warning +whenever a user invokes an operation for the adapted resource and includes the message in the +output of the `dsc resource list` command. + +```yaml +Type: [string, 'null'] +Required: false +``` + ### path -Indicates the path to the adapted resource on the file system. +Indicates the path to the adapted resource on the file system, like the path to the module that +implements a PSDSC resource. DSC passes this value to the adapter when the adapter's operation +definitions include a [resource path argument][10]. ```yaml Type: string Required: true ``` +### description + +Defines a synopsis for the adapted resource's purpose as a short string. + +```yaml +Type: [string, 'null'] +Required: false +``` + ### directory Indicates the path to the folder containing the adapted resource on the file system. @@ -145,22 +180,23 @@ Required: true ### implementedAs -Indicates that the adapted resource uses a custom implementation. The name can be used to -distinguish between different implementations for the adapted resources. +Indicates how the adapted resource is implemented. When the value is `null` or the property is +omitted, DSC treats the resource as a command-based resource. Adapters should set this property to +a string that distinguishes between the implementations of the resources they support. For +example, the PowerShell adapters report `ClassBased`, `ScriptBased`, or `Binary`. ```yaml -Type: string -Required: true +Type: [string, 'null'] +Required: false ``` ### author -Indicates the name of the person or organization that developed and maintains the adapted Resource. +Indicates the name of the person or organization that developed and maintains the adapted resource. ```yaml Type: [string, 'null'] -Required: false -Pattern: ^\w+( \w+)* +Required: false ``` ### properties @@ -168,7 +204,7 @@ Pattern: ^\w+( \w+)* Defines the adapted resource's property names. ```yaml -Type: array +Type: [array, 'null'] Required: false ItemsType: string ItemsPattern: ^\w+$ @@ -177,19 +213,72 @@ ItemsPattern: ^\w+$ ### requireAdapter Defines the fully qualified type name of the adapter that the adapted resource depends on. An -adapter should always set this value to its own fully qualified resource type name. +adapter should always set this value to its own fully qualified resource type name. Although the +schema doesn't mark this property as required, DSC skips any adapted resource that doesn't define +it and logs a warning. ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ +``` + +### schema + +Defines the JSON schema that validates instances of the adapted resource. When an adapter defines +this property for an adapted resource, DSC uses the schema to validate instances of the adapted +resource instead of invoking the adapter's [schema][11] command for the adapted resource. + +```yaml +Type: [object, 'null'] +Required: false +``` + +### targetResource + +Reserved for DSC. When DSC invokes an adapter for an adapted resource, DSC sets this property on +the adapter's representation to the adapted resource. Adapters shouldn't define this property in +the output for the **List** operation. + +```yaml +Type: [object, 'null'] +Required: false +``` + +### manifest + +Represents the values defined in a command-based resource's manifest. Adapted resources don't have +a manifest of their own, so adapters shouldn't define this property in the output for the **List** +operation. + +```yaml +Type: [object, 'null'] +Required: false +``` + +### adaptedContent + +Defines the inline content of the adapted resource as a JSON object. When an adapted resource +manifest defines the resource with the `content` property instead of the `path` property, DSC sets +this property to that content. DSC passes this value to the adapter when the adapter's operation +definitions include an [adapted content argument][12]. This property was added in DSC version +3.3.0. + +```yaml +Type: [object, 'null'] +Required: false ``` -[01]: ../../../resources/Microsoft/DSC/PowerShell/index.md -[02]: ../../../resources/Microsoft/Windows/WindowsPowerShell/index.md -[03]: ../../../resources/Microsoft/Windows/WMI/index.md -[04]: ../../definitions/resourceType.md -[05]: ../../../../concepts/resources/kinds.md -[06]: ../../../../concepts/resources/capabilities.md -[07]: ../../../../concepts/resources/operations.md +[01]: ../manifest/adapter.md#list +[02]: ../../outputs/resource/list.md +[03]: ../../../resources/Microsoft/DSC/PowerShell/index.md +[04]: ../../../resources/Microsoft/Windows/WindowsPowerShell/index.md +[05]: ../../../resources/Microsoft/Windows/WMI/index.md +[06]: ../../definitions/resourceType.md +[07]: ../../../../concepts/resources/kinds.md +[08]: ../../../../concepts/resources/capabilities.md +[09]: ../../../../concepts/resources/operations.md +[10]: ../manifest/get.md#resource-path-argument +[11]: ../manifest/schema/property.md +[12]: ../manifest/get.md#adapted-content-argument diff --git a/docs/reference/schemas/resource/stdout/set.md b/docs/reference/schemas/resource/stdout/set.md index 7fb917962..be7526aca 100644 --- a/docs/reference/schemas/resource/stdout/set.md +++ b/docs/reference/schemas/resource/stdout/set.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the set resource operation -ms.date: 07/29/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource set operation stdout schema reference --- @@ -22,12 +22,14 @@ SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3. Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation. -DSC expects this output for both actual **Set** operations and **Set** operations in `whatIf` mode. -If the resource has the `whatIf` capability, the output should be the same for both modes. +DSC expects this output for actual **Set** operations. For **Set** operations in what-if mode, see +[DSC resource what-if operation stdout schema reference][04]. When the resource has the +`setWhatIf` capability, DSC expects the same output shape in what-if mode unless the resource +manifest defines [set.whatIfReturns][05]. DSC expects different output from the command resource depending on the definition of [set.return][01] in the resource manifest: - + - If the field isn't defined, DSC doesn't expect the resource to return any JSON to stdout. Instead, DSC invokes the **Get** operation on the resource after the **Set** operation concludes and synthesizes the **Set** result, including the after state of the resource and the list of @@ -91,3 +93,5 @@ ItemsType: string [01]: ../manifest/set.md#return [02]: ../manifest/schema/property.md [03]: ../manifest/schema/embedded.md +[04]: ./whatIf.md +[05]: ../manifest/set.md#whatifreturns diff --git a/docs/reference/schemas/resource/stdout/test.md b/docs/reference/schemas/resource/stdout/test.md index 7536bab48..2c4c6c399 100644 --- a/docs/reference/schemas/resource/stdout/test.md +++ b/docs/reference/schemas/resource/stdout/test.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the test resource operation -ms.date: 07/29/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource test operation stdout schema reference --- @@ -25,9 +25,12 @@ Defines the JSON DSC expects a resource to emit to stdout for the **Test** opera DSC expects different output from the command resource depending on the definition of [test.return][01] in the resource manifest: -- If the field is omitted or defined as `state` (the default value), DSC expects the resource to - emit a JSON Line to stdout representing the actual state of the resource instance with the - [_inDesiredState][02] canonical resource property included in the returned object. +- If the field isn't defined, DSC ignores any data the resource emits to stdout. Instead, DSC + invokes the **Get** operation on the resource after the **Test** command concludes and compares + the actual state to the desired state to synthesize the **Test** result. +- If the field is defined as `state`, DSC expects the resource to emit a JSON Line to stdout + representing the actual state of the resource instance with the [_inDesiredState][02] canonical + resource property included in the returned object. - If the field is defined as `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The first JSON Line should be an object representing the actual state of the resource instance with the `_inDesiredState` included in the returned object. The second JSON Line should be an array @@ -35,9 +38,10 @@ DSC expects different output from the command resource depending on the definiti ## state output -For the **Test** operation, DSC always expects the resource to emit a JSON Line to stdout -representing the actual state of the resource instance with the [_inDesiredState][02] canonical -resource property included in the returned object. +When a command resource defines [test.return][01] in its manifest as `state` or `stateAndDiff`, +DSC expects the resource to emit a JSON Line to stdout representing the actual state of the +resource instance with the [_inDesiredState][02] canonical resource property included in the +returned object. The output must be a JSON object. The object must be a valid representation of an instance of the resource. diff --git a/docs/reference/schemas/resource/stdout/whatIf.md b/docs/reference/schemas/resource/stdout/whatIf.md index 9fc08cc77..c341def55 100644 --- a/docs/reference/schemas/resource/stdout/whatIf.md +++ b/docs/reference/schemas/resource/stdout/whatIf.md @@ -1,6 +1,7 @@ --- -description: JSON schema reference for the expected stdout from the set resource operation in what-if mode -ms.date: 07/29/2025 +description: >- + JSON schema reference for the expected stdout from the set resource operation in what-if mode +ms.date: 09/01/2026 ms.topic: reference title: DSC resource what-if operation stdout schema reference --- @@ -22,46 +23,67 @@ SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3. ## Description Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation in what-if -mode. +mode. DSC invokes a resource in what-if mode when a user specifies the `--what-if` option for the +`dsc config set` or `dsc resource set` commands: + +- When the `set` definition in the resource manifest includes a [what-if argument][01], DSC calls + the `set` command with that argument. +- Otherwise, when the resource manifest defines the deprecated [whatIf][02] method, DSC calls that + command. +- Otherwise, DSC synthesizes the what-if result from the **Test** operation and doesn't invoke the + resource in what-if mode. + +DSC expects different output from the command resource depending on the return kind for the +invoked method. The return kind is the value of the [whatIfReturns][03] field for the method when +it's defined, or the value of the [return][04] field otherwise: + +- If neither field is defined, DSC doesn't expect the resource to return any JSON to stdout. + Instead, DSC invokes the **Get** operation on the resource after the command concludes and + synthesizes the result from the state of the resource. +- If the return kind is `state`, DSC expects the resource to emit a JSON Line to stdout + representing the expected state of the resource instance after the **Set** operation would + change the system. +- If the return kind is `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The first + JSON Line should be an object representing the expected state of the resource after the **Set** + operation. The second JSON Line should be an array representing the names of the resource + properties that the operation would change on the system. + +## Null output + +When the return kind for the invoked method isn't defined, DSC doesn't expect the resource to emit +any JSON to stdout in what-if mode. -DSC expects different output from the command resource depending on the definition of -[whatIf.return][01] in the resource manifest: - -- If the field is defined as `state`, DSC expects the resource to emit a JSON Line to stdout - representing the actual state of the resource instance after the **Set** operation changes the - system. -- If the field is defined as `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The - first JSON Line should be an object representing the actual state of the resource after the - **Set** operation. The second JSON Line should be an array representing the names of the resource - properties that the operation changed on the system. +```yaml +Type: 'null' +``` ## state output -When a command resource defines [whatIf.return][01] in its manifest as `state` or `stateAndDiff`, -DSC expects the resource to emit a JSON Line to stdout representing the expected actual state of -the resource instance after the **Set** operation changes the system. +When the return kind for the invoked method is `state` or `stateAndDiff`, DSC expects the resource +to emit a JSON Line to stdout representing the expected actual state of the resource instance after +the **Set** operation would change the system. The output must be a JSON object. The object must be a valid representation of an instance of the resource. -Command resources define their instance schema with the [schema.command][02] or -[schema.embedded][03] fields in their resource manifest. If a command resource returns JSON that is +Command resources define their instance schema with the [schema.command][05] or +[schema.embedded][06] fields in their resource manifest. If a command resource returns JSON that is invalid against the resource instance schema, DSC raises an error. Adapted resource instances are validated by their adapter when the adapter invokes them. ```yaml -type: object +Type: object ``` ## diff output -When a command resource defines [whatIf.return][01] in its manifest as `stateAndDiff`, DSC expects -the resource to emit a second JSON Line to stdout representing the names of the resource properties -that the operation changed on the system. +When the return kind for the invoked method is `stateAndDiff`, DSC expects the resource to emit a +second JSON Line to stdout representing the names of the resource properties that the operation +would change on the system. -This output must be emitted after the JSON Line representing the state of the resource instance -after the operation changes the system. +This output must be emitted after the JSON Line representing the expected state of the resource +instance after the operation would change the system. The output must be a JSON array. The array may be empty, or it may contain one or more strings. Each string in the array must be the name of one of the resource's properties. Each string in the @@ -74,6 +96,9 @@ ItemsType: string ``` -[01]: ../manifest/whatif.md#return -[02]: ../manifest/schema/property.md -[03]: ../manifest/schema/embedded.md +[01]: ../manifest/set.md#what-if-argument +[02]: ../manifest/whatif.md +[03]: ../manifest/set.md#whatifreturns +[04]: ../manifest/set.md#return +[05]: ../manifest/schema/property.md +[06]: ../manifest/schema/embedded.md