From 1463fdac9df7c05a436243fcf13eb9f5a1b3651d Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Fri, 4 Sep 2026 04:44:06 +0200 Subject: [PATCH] docs: Refresh configuration function reference --- .../reference/schemas/config/functions/add.md | 4 +- .../schemas/config/functions/array.md | 4 +- .../config/functions/base64ToString.md | 4 +- .../schemas/config/functions/bool.md | 4 +- .../schemas/config/functions/cidrHost.md | 20 +- .../schemas/config/functions/cidrSubnet.md | 30 +- .../schemas/config/functions/coalesce.md | 4 +- .../schemas/config/functions/concat.md | 5 +- .../schemas/config/functions/contains.md | 31 +- .../schemas/config/functions/copy.md | 51 ++- .../schemas/config/functions/createObject.md | 21 +- .../schemas/config/functions/dataUri.md | 7 +- .../config/functions/dataUriToString.md | 5 +- .../reference/schemas/config/functions/div.md | 8 +- .../schemas/config/functions/empty.md | 8 +- .../schemas/config/functions/endsWith.md | 6 +- .../schemas/config/functions/equals.md | 20 +- .../schemas/config/functions/filter.md | 303 +++++++++++++++++ .../schemas/config/functions/greater.md | 7 +- .../config/functions/greaterOrEquals.md | 7 +- docs/reference/schemas/config/functions/if.md | 28 +- .../schemas/config/functions/indexOf.md | 7 +- .../schemas/config/functions/intersection.md | 35 +- .../schemas/config/functions/items.md | 4 +- .../schemas/config/functions/join.md | 19 +- .../schemas/config/functions/json.md | 14 +- .../schemas/config/functions/lambda.md | 280 ++++++++++++++++ .../config/functions/lambdaVariables.md | 240 ++++++++++++++ .../schemas/config/functions/last.md | 4 +- .../schemas/config/functions/lastIndexOf.md | 20 +- .../schemas/config/functions/length.md | 8 +- .../schemas/config/functions/less.md | 7 +- .../schemas/config/functions/lessOrEquals.md | 4 +- .../reference/schemas/config/functions/map.md | 313 ++++++++++++++++++ .../reference/schemas/config/functions/mul.md | 16 +- .../schemas/config/functions/null.md | 5 +- .../schemas/config/functions/objectKeys.md | 11 +- .../schemas/config/functions/overview.md | 224 ++++++++----- .../schemas/config/functions/parameters.md | 11 +- .../schemas/config/functions/parseCidr.md | 6 +- .../schemas/config/functions/path.md | 20 +- .../schemas/config/functions/range.md | 4 +- .../schemas/config/functions/reference.md | 14 +- .../schemas/config/functions/resourceId.md | 18 +- .../schemas/config/functions/shallowMerge.md | 168 +++++----- .../schemas/config/functions/skip.md | 4 +- .../schemas/config/functions/startsWith.md | 6 +- .../schemas/config/functions/stateChanged.md | 6 +- .../schemas/config/functions/stdout.md | 179 ++++++++++ .../schemas/config/functions/string.md | 19 +- .../reference/schemas/config/functions/sub.md | 6 +- .../schemas/config/functions/systemRoot.md | 10 +- .../schemas/config/functions/take.md | 7 +- .../schemas/config/functions/toLower.md | 9 +- .../schemas/config/functions/toUpper.md | 10 +- .../schemas/config/functions/tryGet.md | 29 +- .../config/functions/tryIndexFromEnd.md | 17 +- .../schemas/config/functions/tryWhich.md | 21 +- .../schemas/config/functions/union.md | 14 +- .../schemas/config/functions/uniqueString.md | 8 +- .../reference/schemas/config/functions/uri.md | 6 +- .../schemas/config/functions/uriComponent.md | 6 +- .../config/functions/uriComponentToString.md | 31 +- lib/dsc-lib/src/parser/functions.rs | 4 +- 64 files changed, 1995 insertions(+), 426 deletions(-) create mode 100644 docs/reference/schemas/config/functions/filter.md create mode 100644 docs/reference/schemas/config/functions/lambda.md create mode 100644 docs/reference/schemas/config/functions/lambdaVariables.md create mode 100644 docs/reference/schemas/config/functions/map.md create mode 100644 docs/reference/schemas/config/functions/stdout.md diff --git a/docs/reference/schemas/config/functions/add.md b/docs/reference/schemas/config/functions/add.md index ddf0c4c1b..ee08f2c27 100644 --- a/docs/reference/schemas/config/functions/add.md +++ b/docs/reference/schemas/config/functions/add.md @@ -1,6 +1,6 @@ --- description: Reference for the 'add' DSC configuration document function -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: add --- @@ -39,7 +39,7 @@ resources: ``` ```bash -dsc config get --file add.example.1.dsc.config.yaml +dsc config get --file add.example.1.dsc.config.yaml ``` ```yaml diff --git a/docs/reference/schemas/config/functions/array.md b/docs/reference/schemas/config/functions/array.md index 87839626f..7150eaf6c 100644 --- a/docs/reference/schemas/config/functions/array.md +++ b/docs/reference/schemas/config/functions/array.md @@ -1,6 +1,6 @@ --- description: Reference for the 'array' DSC configuration document function -ms.date: 08/12/2025 +ms.date: 09/01/2026 ms.topic: reference title: array --- @@ -153,7 +153,7 @@ The single value to wrap in the array. ```yaml Type: string, number, array, or object -Required: false +Required: true MinimumCount: 1 MaximumCount: 1 ``` diff --git a/docs/reference/schemas/config/functions/base64ToString.md b/docs/reference/schemas/config/functions/base64ToString.md index 2f5c02731..002b6991c 100644 --- a/docs/reference/schemas/config/functions/base64ToString.md +++ b/docs/reference/schemas/config/functions/base64ToString.md @@ -1,6 +1,6 @@ --- description: Reference for the 'base64ToString' DSC configuration document function -ms.date: 09/30/2025 +ms.date: 09/01/2026 ms.topic: reference title: base64ToString --- @@ -70,7 +70,7 @@ resources: ``` ```bash -dsc config get --file base64ToString.example.2.dsc.config.yaml +dsc config get --file base64ToString.example.2.dsc.config.yaml ``` ```yaml diff --git a/docs/reference/schemas/config/functions/bool.md b/docs/reference/schemas/config/functions/bool.md index b1ac488ce..67b892599 100644 --- a/docs/reference/schemas/config/functions/bool.md +++ b/docs/reference/schemas/config/functions/bool.md @@ -1,6 +1,6 @@ --- description: Reference for the 'bool' DSC configuration document function -ms.date: 01/19/2025 +ms.date: 09/01/2026 ms.topic: reference title: bool --- @@ -112,10 +112,12 @@ hadErrors: false The `bool()` function requires a single argument that is either a string or number. For strings, valid values are: + - "true" (case-insensitive) - converts to `true` - "false" (case-insensitive) - converts to `false` For numbers: + - 0 - converts to `false` - Any non-zero value - converts to `true` diff --git a/docs/reference/schemas/config/functions/cidrHost.md b/docs/reference/schemas/config/functions/cidrHost.md index 0de44842d..e74ae4e70 100644 --- a/docs/reference/schemas/config/functions/cidrHost.md +++ b/docs/reference/schemas/config/functions/cidrHost.md @@ -1,6 +1,6 @@ --- description: Reference for the 'cidrHost' DSC configuration document function -ms.date: 11/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: cidrHost --- @@ -83,9 +83,15 @@ resources: properties: output: subnet: "[cidrSubnet(parameters('baseNetwork'), 24, parameters('subnetIndex'))]" - webServer1: "[cidrHost(cidrSubnet(parameters('baseNetwork'), 24, parameters('subnetIndex')), 10)]" - webServer2: "[cidrHost(cidrSubnet(parameters('baseNetwork'), 24, parameters('subnetIndex')), 11)]" - webServer3: "[cidrHost(cidrSubnet(parameters('baseNetwork'), 24, parameters('subnetIndex')), 12)]" + webServer1: >- + [cidrHost(cidrSubnet(parameters('baseNetwork'), 24, + parameters('subnetIndex')), 10)] + webServer2: >- + [cidrHost(cidrSubnet(parameters('baseNetwork'), 24, + parameters('subnetIndex')), 11)] + webServer3: >- + [cidrHost(cidrSubnet(parameters('baseNetwork'), 24, + parameters('subnetIndex')), 12)] ``` ```bash @@ -100,9 +106,9 @@ results: actualState: output: subnet: 172.16.10.0/24 - webServer1: 172.16.10.10 - webServer2: 172.16.10.11 - webServer3: 172.16.10.12 + webServer1: 172.16.10.11 + webServer2: 172.16.10.12 + webServer3: 172.16.10.13 messages: [] hadErrors: false ``` diff --git a/docs/reference/schemas/config/functions/cidrSubnet.md b/docs/reference/schemas/config/functions/cidrSubnet.md index bf4ac7e74..82da1fd7d 100644 --- a/docs/reference/schemas/config/functions/cidrSubnet.md +++ b/docs/reference/schemas/config/functions/cidrSubnet.md @@ -1,6 +1,6 @@ --- description: Reference for the 'cidrSubnet' DSC configuration document function -ms.date: 11/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: cidrSubnet --- @@ -96,7 +96,8 @@ resources: westus: "[cidrSubnet(parameters('baseNetwork'), parameters('newPrefix'), 1)]" northeurope: "[cidrSubnet(parameters('baseNetwork'), parameters('newPrefix'), 2)]" westeurope: "[cidrSubnet(parameters('baseNetwork'), parameters('newPrefix'), 3)]" - southeastasia: "[cidrSubnet(parameters('baseNetwork'), parameters('newPrefix'), 4)]" + southeastasia: >- + [cidrSubnet(parameters('baseNetwork'), parameters('newPrefix'), 4)] ``` ```bash @@ -142,9 +143,15 @@ resources: output: vnetAddressSpace: "[parameters('vnetCidr')]" subnetCidr: "[cidrSubnet(parameters('vnetCidr'), 24, parameters('subnetIndex'))]" - subnetDetails: "[parseCidr(cidrSubnet(parameters('vnetCidr'), 24, parameters('subnetIndex')))]" - gatewayIP: "[cidrHost(cidrSubnet(parameters('vnetCidr'), 24, parameters('subnetIndex')), 1)]" - loadBalancerIP: "[cidrHost(cidrSubnet(parameters('vnetCidr'), 24, parameters('subnetIndex')), 4)]" + subnetDetails: >- + [parseCidr(cidrSubnet(parameters('vnetCidr'), 24, + parameters('subnetIndex')))] + gatewayIP: >- + [cidrHost(cidrSubnet(parameters('vnetCidr'), 24, + parameters('subnetIndex')), 1)] + loadBalancerIP: >- + [cidrHost(cidrSubnet(parameters('vnetCidr'), 24, + parameters('subnetIndex')), 4)] ``` ```bash @@ -167,8 +174,8 @@ results: firstUsable: 172.16.42.1 lastUsable: 172.16.42.254 cidr: 24 - gatewayIP: 172.16.42.1 - loadBalancerIP: 172.16.42.4 + gatewayIP: 172.16.42.2 + loadBalancerIP: 172.16.42.5 messages: [] hadErrors: false ``` @@ -194,9 +201,12 @@ resources: properties: output: baseNetwork: "[parameters('ipv6BaseNetwork')]" - subnet0: "[cidrSubnet(parameters('ipv6BaseNetwork'), parameters('subnetPrefix'), 0)]" - subnet1: "[cidrSubnet(parameters('ipv6BaseNetwork'), parameters('subnetPrefix'), 1)]" - subnet10: "[cidrSubnet(parameters('ipv6BaseNetwork'), parameters('subnetPrefix'), 10)]" + subnet0: >- + [cidrSubnet(parameters('ipv6BaseNetwork'), parameters('subnetPrefix'), 0)] + subnet1: >- + [cidrSubnet(parameters('ipv6BaseNetwork'), parameters('subnetPrefix'), 1)] + subnet10: >- + [cidrSubnet(parameters('ipv6BaseNetwork'), parameters('subnetPrefix'), 10)] ``` ```bash diff --git a/docs/reference/schemas/config/functions/coalesce.md b/docs/reference/schemas/config/functions/coalesce.md index ce2f00016..d3dae8385 100644 --- a/docs/reference/schemas/config/functions/coalesce.md +++ b/docs/reference/schemas/config/functions/coalesce.md @@ -1,6 +1,6 @@ --- description: Reference for the 'coalesce' DSC configuration document function -ms.date: 07/24/2025 +ms.date: 09/01/2026 ms.topic: reference title: coalesce --- @@ -38,7 +38,7 @@ resources: - name: Coalesce strings type: Microsoft.DSC.Debug/Echo properties: - output: + output: firstNonNull: "[coalesce(null(), 'DSC', 'landscape')]" allNull: "[coalesce(null(), null(), null())]" noneNull: "[coalesce('first', 'second', 'third')]" diff --git a/docs/reference/schemas/config/functions/concat.md b/docs/reference/schemas/config/functions/concat.md index c54ec1e64..cd9347979 100644 --- a/docs/reference/schemas/config/functions/concat.md +++ b/docs/reference/schemas/config/functions/concat.md @@ -1,6 +1,6 @@ --- description: Reference for the 'concat' DSC configuration document function -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: concat --- @@ -60,7 +60,8 @@ hadErrors: false ### Example 2 - Concatenate arrays of strings -The configuration uses the `concat()` function to return a combined array of strings from two arrays of strings. It uses YAML's folded multiline syntax to make the function more readable. +The configuration uses the `concat()` function to return a combined array of strings from two +arrays of strings. It uses YAML's folded multiline syntax to make the function more readable. ```yaml # concat.example.2.dsc.config.yaml diff --git a/docs/reference/schemas/config/functions/contains.md b/docs/reference/schemas/config/functions/contains.md index 76fc4db1a..18689e588 100644 --- a/docs/reference/schemas/config/functions/contains.md +++ b/docs/reference/schemas/config/functions/contains.md @@ -1,6 +1,6 @@ --- description: Reference for the 'contains' DSC configuration document function -ms.date: 08/08/2025 +ms.date: 09/01/2026 ms.topic: reference title: contains --- @@ -23,11 +23,14 @@ contains(, ) The `contains()` function checks whether a collection (array, object, or string) contains a specific value, returning `true` if it does and `false` otherwise. For arrays, it checks if the value exists as an element. For -objects, it checks if the value exists as a property key or value. For -strings, it checks if the value exists as a substring. +objects, it checks if the value exists as a property key. The function +doesn't check object property values. For strings, it checks if the value +exists as a substring. The function accepts string and number values for the search parameter when -used with arrays, objects, or strings. +used with arrays, objects, or strings. When the search value is a number and +the collection is an object or a string, DSC compares the number by its +string representation. ## Examples @@ -76,10 +79,12 @@ messages: [] hadErrors: false ``` -### Example 2 - Check object for keys and values +### Example 2 - Check object for keys -The following example shows how to check if an object contains specific keys -or values. +The following example shows how to check if an object contains specific keys. +For objects, `contains()` only checks keys, not property values. To check the +contents of a property value, access the property and check it as a string, +like the `cityHasSeattle` output in this example. ```yaml # contains.example.2.dsc.config.yaml @@ -96,10 +101,10 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - hasNameKey: "[contains(parameters('myObject'), 'name')]" - hasEmailKey: "[contains(parameters('myObject'), 'email')]" - hasSeattleValue: "[contains(parameters('myObject').city, 'Seattle')]" - hasAge30Value: "[contains(parameters('myObject').age, 30)]" + hasNameKey: "[contains(parameters('myObject'), 'name')]" + hasEmailKey: "[contains(parameters('myObject'), 'email')]" + hasAgeKey: "[contains(parameters('myObject'), 'age')]" + cityHasSeattle: "[contains(parameters('myObject').city, 'Seattle')]" ``` ```bash @@ -115,8 +120,8 @@ results: output: hasNameKey: true hasEmailKey: false - hasSeattleValue: true - hasAge30Value: true + hasAgeKey: true + cityHasSeattle: true messages: [] hadErrors: false ``` diff --git a/docs/reference/schemas/config/functions/copy.md b/docs/reference/schemas/config/functions/copy.md index 1c1312ecb..e1f4c3cac 100644 --- a/docs/reference/schemas/config/functions/copy.md +++ b/docs/reference/schemas/config/functions/copy.md @@ -1,6 +1,6 @@ --- description: Reference for the 'copy' DSC configuration document resource loop -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: copy --- @@ -23,8 +23,16 @@ copy: The `copy` property enables you to create multiple instances of a resource in a DSC configuration. This is the equivalent implementation of the copy -functionality from Azure Resource Manager (ARM) templates, but without support -for variables and properties, which will be added in future releases. +functionality from Azure Resource Manager (ARM) templates. DSC only supports +copy loops on resource instances. Copy loops for variables and resource +properties aren't supported. A configuration output can define `copy`, but DSC +ignores that output and emits a warning that copy loops for outputs aren't +supported. + +> [!IMPORTANT] +> Copy loops are deprecated. When DSC expands a copy loop, it emits a warning +> that the copy loop is deprecated and will be removed in a future release. For +> more information, see [issue #1429][03] in the DSC repository. When you use `copy` on a resource, DSC creates multiple instances of that resource based on the specified count. You can use the [`copyIndex()`][01] @@ -186,27 +194,32 @@ resources: ``` ```bash -dsc config get --file copy.example.4.dsc.config.yaml --parameters '{"instanceCount": 4}' +params='{"parameters": {"instanceCount": 4}}' +dsc config --parameters "$params" get --file copy.example.4.dsc.config.yaml ``` ```yaml results: -- metadata: - Microsoft.DSC: - duration: PT0.2173106S - name: Dynamic-0 +- name: Dynamic-0 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Instance 0 of 4 +- name: Dynamic-1 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Instance 1 of 4 +- name: Dynamic-2 type: Microsoft.DSC.Debug/Echo result: actualState: - output: Instance 0 of 2 -- metadata: - Microsoft.DSC: - duration: PT0.0161486S - name: Dynamic-1 + output: Instance 2 of 4 +- name: Dynamic-3 type: Microsoft.DSC.Debug/Echo result: actualState: - output: Instance 1 of 2 + output: Instance 3 of 4 messages: [] hadErrors: false ``` @@ -261,13 +274,16 @@ resources to create in each batch when using parallel mode. The current implementation has the following limitations: -- **Variables and properties**: Copy loops for variables and properties are not - yet supported. +- **Deprecation**: Copy loops are deprecated. DSC emits a warning when it + expands a copy loop. For more information, see [issue #1429][03]. +- **Resources only**: Copy loops are only supported on resource instances. Copy + loops for variables and resource properties aren't supported. DSC ignores a + `copy` definition on a configuration output and emits a warning. - **Mode control**: The `mode` property (serial/parallel) is not implemented. - **Batch processing**: The `batchSize` property is not implemented. - **Name expressions**: The resource name expression must evaluate to a string. -## Related Functions +## Related functions - [`copyIndex()`][01] - Returns the current iteration index of a copy loop. - [`parameters()`][02] - Returns the value of a configuration parameter. @@ -275,3 +291,4 @@ The current implementation has the following limitations: [01]: ./copyIndex.md [02]: ./parameters.md +[03]: https://github.com/PowerShell/DSC/issues/1429 diff --git a/docs/reference/schemas/config/functions/createObject.md b/docs/reference/schemas/config/functions/createObject.md index 5ee3bae92..2a59ed7f4 100644 --- a/docs/reference/schemas/config/functions/createObject.md +++ b/docs/reference/schemas/config/functions/createObject.md @@ -1,10 +1,12 @@ --- description: Reference for the 'createObject' DSC configuration document function -ms.date: 07/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: createObject --- +# createObject + ## Synopsis Creates a JSON object from key-value pairs. @@ -75,7 +77,9 @@ resources: - name: Mixed data types type: Microsoft.DSC.Debug/Echo properties: - output: "[createObject('string', 'hello', 'number', 123, 'boolean', true, 'nullValue', null())]" + output: >- + [createObject('string', 'hello', 'number', 123, 'boolean', true, + 'nullValue', null())] ``` ```bash @@ -109,7 +113,8 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - nestedObject: "[createObject('config', createObject('timeout', 30, 'enabled', true))]" + nestedObject: >- + [createObject('config', createObject('timeout', 30, 'enabled', true))] objectWithArray: "[createObject('items', createArray('foo', 'bar', 'baz'))]" ``` @@ -153,8 +158,11 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - userConfig: "[createObject('user', parameters('userName'), 'role', coalesce(null(), 'default'))]" - fallbackObject: "[createObject('result', coalesce(null(), createObject('status', 'success')))]" + userConfig: >- + [createObject('user', parameters('userName'), 'role', + coalesce(null(), 'default'))] + fallbackObject: >- + [createObject('result', coalesce(null(), createObject('status', 'success')))] ``` ```bash @@ -203,7 +211,8 @@ Required: true (when providing values) #### value -The object property value. Can be any valid JSON type including strings, numbers, booleans, null, arrays, or other objects. +The object property value. Can be any valid JSON type including strings, numbers, booleans, null, +arrays, or other objects. ```yaml Type: [any] diff --git a/docs/reference/schemas/config/functions/dataUri.md b/docs/reference/schemas/config/functions/dataUri.md index 27ce3b44c..f722f3047 100644 --- a/docs/reference/schemas/config/functions/dataUri.md +++ b/docs/reference/schemas/config/functions/dataUri.md @@ -1,6 +1,6 @@ --- description: Reference for the 'dataUri' DSC configuration document function -ms.date: 12/20/2025 +ms.date: 09/01/2026 ms.topic: reference title: dataUri --- @@ -20,8 +20,7 @@ dataUri() ## Description The `dataUri()` function converts a string value to a [data URI][01] format. The function encodes -the input string as base64 and returns it as a data URI with the `application/json` media type and -`utf8` charset. +the input string as base64 and returns it as a data URI with the `application/json` media type. Data URIs are useful for embedding small text content directly in configuration documents, especially when the content needs to be passed through systems that expect URI-formatted data. @@ -179,7 +178,7 @@ MaximumCount: 1 ## Output The `dataUri()` function returns a data URI string in the format -`data:application/json;charset=utf8;base64,` where `` is the base64 +`data:application/json;base64,` where `` is the base64 representation of the **stringToConvert** value. ```yaml diff --git a/docs/reference/schemas/config/functions/dataUriToString.md b/docs/reference/schemas/config/functions/dataUriToString.md index 9885fcb0a..0b87ec8f2 100644 --- a/docs/reference/schemas/config/functions/dataUriToString.md +++ b/docs/reference/schemas/config/functions/dataUriToString.md @@ -1,6 +1,6 @@ --- description: Reference for the 'dataUriToString' DSC configuration document function -ms.date: 12/20/2025 +ms.date: 09/01/2026 ms.topic: reference title: dataUriToString --- @@ -39,7 +39,8 @@ $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json parameters: encodedScript: type: string - defaultValue: "data:text/plain;charset=utf8;base64,V3JpdGUtSG9zdCAnSGVsbG8sIFdvcmxkISc=" + defaultValue: "data:text/plain;charset=utf8;base64,\ + V3JpdGUtSG9zdCAnSGVsbG8sIFdvcmxkISc=" resources: - name: Decode and display script type: Microsoft.DSC.Debug/Echo diff --git a/docs/reference/schemas/config/functions/div.md b/docs/reference/schemas/config/functions/div.md index 110d5e65d..ca3ce9eac 100644 --- a/docs/reference/schemas/config/functions/div.md +++ b/docs/reference/schemas/config/functions/div.md @@ -1,6 +1,6 @@ --- description: Reference for the 'div' DSC configuration document function -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: div --- @@ -90,9 +90,9 @@ hadErrors: false ### operands -The `div()` function expects exactly two integers as input. The **operands** can be either an integer -or the output of any configuration function that returns an integer. The function divides the -first operand by the second operand. Separate the **operands** with a comma (`,`). +The `div()` function expects exactly two integers as input. The **operands** can be either an +integer or the output of any configuration function that returns an integer. The function divides +the first operand by the second operand. Separate the **operands** with a comma (`,`). ```yaml Type: integer diff --git a/docs/reference/schemas/config/functions/empty.md b/docs/reference/schemas/config/functions/empty.md index 90fc2a200..6b8199bd2 100644 --- a/docs/reference/schemas/config/functions/empty.md +++ b/docs/reference/schemas/config/functions/empty.md @@ -1,6 +1,6 @@ --- description: Reference for the 'empty' DSC configuration document function -ms.date: 08/08/2025 +ms.date: 09/01/2026 ms.topic: reference title: empty --- @@ -170,7 +170,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - message: "[if(empty(parameters('serverList')), 'No servers to configure', concat('Configuring ', string(length(parameters('serverList'))), ' servers'))]" + message: >- + [if(empty(parameters('serverList')), 'No servers to configure', + concat('Configuring ', string(length(parameters('serverList'))), ' servers'))] ``` ```bash @@ -184,7 +186,7 @@ results: result: actualState: output: - message: "No servers to configure" + message: No servers to configure messages: [] hadErrors: false ``` diff --git a/docs/reference/schemas/config/functions/endsWith.md b/docs/reference/schemas/config/functions/endsWith.md index 2cafddfae..bcccca96e 100644 --- a/docs/reference/schemas/config/functions/endsWith.md +++ b/docs/reference/schemas/config/functions/endsWith.md @@ -1,6 +1,6 @@ --- description: Reference for the 'endsWith' DSC configuration document function -ms.date: 08/12/2025 +ms.date: 09/01/2026 ms.topic: reference title: endsWith --- @@ -78,7 +78,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - classification: "[if(endsWith(parameters('environment'), '-prod'), 'Production', 'Non-production')]" + classification: >- + [if(endsWith(parameters('environment'), '-prod'), 'Production', + 'Non-production')] ``` ```bash diff --git a/docs/reference/schemas/config/functions/equals.md b/docs/reference/schemas/config/functions/equals.md index 7dad419b9..1b27a06ee 100644 --- a/docs/reference/schemas/config/functions/equals.md +++ b/docs/reference/schemas/config/functions/equals.md @@ -1,6 +1,6 @@ --- description: Reference for the 'equals' DSC configuration document function -ms.date: 07/02/2025 +ms.date: 09/01/2026 ms.topic: reference title: equals --- @@ -14,7 +14,7 @@ Checks whether two values are identical. ## Syntax ```Syntax -equals() +equals(, ) ``` ## Description @@ -36,7 +36,7 @@ resources: - name: Compare strings type: Microsoft.DSC.Debug/Echo properties: - output: + output: sameCase: "[equals('a', 'a')]" differentCase: "[equals('a', 'A')]" differentLetters: "[equals('a', 'b')]" @@ -89,9 +89,6 @@ results: output: sameInteger: true differentInteger: false - sameFloat: true - differentFloat: false - integerAndFloat: ? messages: [] hadErrors: false ``` @@ -159,14 +156,17 @@ hadErrors: false ### inputValue -The `equals()` function expects exactly two input values of the same type. Separate each value with -a comma. If the type of the second input value is different from the first value, DSC returns an -error for the function. +The `equals()` function expects exactly two input values. Separate each value with a comma. If +the type of the second input value is different from the first value, DSC returns `false` for +the function. String comparisons are case-sensitive. Array comparisons are position-sensitive. +The function doesn't accept boolean values. DSC raises an error when either input value is a +boolean. + ```yaml -Type: [integer, string, object, array] +Type: [null, integer, string, object, array] Required: true MinimumCount: 2 MaximumCount: 2 diff --git a/docs/reference/schemas/config/functions/filter.md b/docs/reference/schemas/config/functions/filter.md new file mode 100644 index 000000000..7329fe016 --- /dev/null +++ b/docs/reference/schemas/config/functions/filter.md @@ -0,0 +1,303 @@ +--- +description: Reference for the 'filter' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: filter +--- + +# filter + +## Synopsis + +Returns a new array that contains only the elements of an input array for which a lambda function +returns `true`. + +## Syntax + +```Syntax +filter(, ) +``` + +## Description + +The `filter()` function evaluates a lambda function created with [`lambda()`][00] against every +element of an array and returns a new array that contains only the elements for which the lambda +returned `true`. The function doesn't change the elements it keeps. It copies them to the output +array in their original order. + +For each element in the input array, DSC: + +1. Binds the element to the lambda's first parameter. +1. Binds the zero-based index of the element to the lambda's second parameter, if the lambda + declares one. +1. Evaluates the lambda's body expression. Inside the body, use [`lambdaVariables()`][01] to read + the bound parameters. +1. Includes the element in the output when the body returns `true` and skips it when the body + returns `false`. + +The lambda body must return a boolean value. If it returns a value of any other type, DSC raises +an error and stops processing the configuration document. + +The lambda body can call any other configuration function. DSC evaluates the body with a copy of +the current context, so the body can read configuration [`parameters()`][02] and +[`variables()`][03] in addition to the lambda's own parameters. + +This function is useful for: + +- Selecting the subset of an array that meets a condition before passing it to a resource. +- Filtering an array of objects by the value of one of their properties. +- Keeping only specific positions of an array by testing the index parameter. + +## Examples + +### Example 1 - Filter numbers by value + +The following example keeps only the numbers greater than `2`. The lambda declares a single +parameter, `x`, which DSC binds to each element in turn. The [`greater()`][04] function returns +the boolean value that `filter()` requires. + +```yaml +# filter.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + numbers: + type: array + defaultValue: [1, 2, 3, 4, 5] +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [filter( + parameters('numbers'), + lambda('x', greater(lambdaVariables('x'), 2)) + )] +``` + +```bash +dsc config get --file filter.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - 3 + - 4 + - 5 +messages: [] +hadErrors: false +``` + +### Example 2 - Filter elements by index + +The following example uses a lambda with two parameters. DSC binds the element to `val` and the +zero-based index of the element to `i`. The lambda uses [`less()`][05] on the index to keep only +the first two elements. + +```yaml +# filter.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + items: + type: array + defaultValue: [10, 20, 30, 40] +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [filter( + parameters('items'), + lambda('val', 'i', less(lambdaVariables('i'), 2)) + )] +``` + +```bash +dsc config get --file filter.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - 10 + - 20 +messages: [] +hadErrors: false +``` + +### Example 3 - Filter objects by a property + +The following example filters an array of objects. The lambda body accesses the `enabled` +property of each element with the property access syntax. Because the property is already a +boolean value, the lambda returns it directly. + +```yaml +# filter.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + services: + type: array + defaultValue: + - name: web + enabled: true + - name: database + enabled: false + - name: cache + enabled: true +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [filter( + parameters('services'), + lambda('service', lambdaVariables('service').enabled) + )] +``` + +```bash +dsc config get --file filter.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - name: web + enabled: true + - name: cache + enabled: true +messages: [] +hadErrors: false +``` + +The output contains the complete objects that matched, not just the property that was tested. + +### Example 4 - Filter strings by prefix + +The following example uses [`startsWith()`][06] in the lambda body to keep only the strings that +start with `prod-`. + +```yaml +# filter.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [filter( + createArray('prod-web', 'dev-web', 'prod-db', 'test-db'), + lambda('name', startsWith(lambdaVariables('name'), 'prod-')) + )] +``` + +```bash +dsc config get --file filter.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - prod-web + - prod-db +messages: [] +hadErrors: false +``` + +## Parameters + +### inputArray + +The array whose elements to test. The elements can be of any type, including objects and nested +arrays. + +```yaml +Type: array +Required: true +Position: 1 +``` + +### lambda + +A lambda function created with [`lambda()`][00]. The lambda must declare one or two parameters. +DSC binds the current element to the first parameter and the zero-based index of the element to +the optional second parameter. The lambda's body must return a boolean value. + +```yaml +Type: lambda +Required: true +Position: 2 +``` + +## Output + +Returns an array containing the elements of `inputArray` for which the lambda returned `true`, in +their original order. Returns an empty array when no elements match or when `inputArray` is empty. + +```yaml +Type: array +``` + +## Error conditions + +The function raises an error in the following cases: + +- **Not an array**: The first argument isn't an array. For example, passing a string raises + `Function 'filter' does not accept string arguments, accepted types are: Array`. +- **Not a lambda**: The second argument isn't a lambda created with [`lambda()`][00]. +- **Too many parameters**: The lambda declares more than two parameters. DSC raises + `Function 'filter' requires lambda with 1 or 2 parameters (element and optional index)`. +- **Non-boolean result**: The lambda body returns a value that isn't a boolean. DSC raises + `filter() lambda must return a boolean value`. +- **Body error**: The lambda body raises an error. For example, calling + [`lambdaVariables()`][01] with a name that the lambda didn't declare raises + `Lambda parameter '' not found in current context`. + +## Notes + +- The function doesn't transform the elements it keeps. To change the elements of an array, use + [`map()`][07] instead. +- The function evaluates the lambda body once for each element in the input array. When the input + array is empty, the body is never evaluated and the function returns an empty array. +- The index that DSC binds to the optional second parameter is a zero-based number. +- Lambda parameters are separate from configuration variables. Read them with + [`lambdaVariables()`][01], not [`variables()`][03]. + +## Related functions + +- [`lambda()`][00] - Creates the lambda function that `filter()` evaluates +- [`lambdaVariables()`][01] - Reads a lambda parameter inside the lambda body +- [`map()`][07] - Transforms every element of an array with a lambda +- [`parameters()`][02] - Returns the value of a configuration parameter +- [`variables()`][03] - Returns the value of a configuration variable +- [`greater()`][04] - Checks whether the first value is greater than the second value +- [`less()`][05] - Checks whether the first value is less than the second value +- [`startsWith()`][06] - Checks whether a string starts with a prefix +- [`createArray()`][08] - Creates an array from values + + +[00]: ./lambda.md +[01]: ./lambdaVariables.md +[02]: ./parameters.md +[03]: ./variables.md +[04]: ./greater.md +[05]: ./less.md +[06]: ./startsWith.md +[07]: ./map.md +[08]: ./createArray.md diff --git a/docs/reference/schemas/config/functions/greater.md b/docs/reference/schemas/config/functions/greater.md index 6b050fd96..e84a2a9c7 100644 --- a/docs/reference/schemas/config/functions/greater.md +++ b/docs/reference/schemas/config/functions/greater.md @@ -1,6 +1,6 @@ --- description: Reference for the 'greater' DSC configuration document function -ms.date: 07/24/2025 +ms.date: 09/01/2026 ms.topic: reference title: greater --- @@ -24,7 +24,8 @@ returning `true` if it is and otherwise `false`. You can use this function to co values of the same data type. If the values are different types, like a string and an integer, DSC returns an error for this function. -For strings, the comparison is case-sensitive and uses lexicographic ordering based on character codes. +For strings, the comparison is case-sensitive and uses lexicographic ordering based on character +codes. ## Examples @@ -39,7 +40,7 @@ resources: - name: Compare numbers type: Microsoft.DSC.Debug/Echo properties: - output: + output: firstGreater: "[greater(5, 3)]" secondGreater: "[greater(3, 5)]" equalNumbers: "[greater(5, 5)]" diff --git a/docs/reference/schemas/config/functions/greaterOrEquals.md b/docs/reference/schemas/config/functions/greaterOrEquals.md index d6e970ba8..5072e0259 100644 --- a/docs/reference/schemas/config/functions/greaterOrEquals.md +++ b/docs/reference/schemas/config/functions/greaterOrEquals.md @@ -1,6 +1,6 @@ --- description: Reference for the 'greaterOrEquals' DSC configuration document function -ms.date: 07/24/2025 +ms.date: 09/01/2026 ms.topic: reference title: greaterOrEquals --- @@ -24,7 +24,8 @@ than or equal to the second value, returning `true` if it is and otherwise `fals You can use this function to compare two values of the same data type. If the values are different types, like a string and an integer, DSC returns an error for this function. -For strings, the comparison is case-sensitive and uses lexicographic ordering based on character codes. +For strings, the comparison is case-sensitive and uses lexicographic ordering based on character +codes. ## Examples @@ -39,7 +40,7 @@ resources: - name: Compare numbers type: Microsoft.DSC.Debug/Echo properties: - output: + output: firstGreater: "[greaterOrEquals(5, 3)]" secondGreater: "[greaterOrEquals(3, 5)]" equalNumbers: "[greaterOrEquals(5, 5)]" diff --git a/docs/reference/schemas/config/functions/if.md b/docs/reference/schemas/config/functions/if.md index faf1dd7cf..71f13e345 100644 --- a/docs/reference/schemas/config/functions/if.md +++ b/docs/reference/schemas/config/functions/if.md @@ -1,6 +1,6 @@ --- description: Reference for the 'if' DSC configuration document function -ms.date: 07/02/2025 +ms.date: 09/01/2026 ms.topic: reference title: if --- @@ -22,6 +22,10 @@ if(, , ) The `if()` function returns a value based on whether a condition is true or false. You can use this function to conditionally use different values in a configuration document. +The values to return must be strings, integers, objects, or arrays. The function doesn't accept +boolean or null values for `trueValue` or `falseValue`. For more information, see +[Error conditions](#error-conditions). + ## Examples ### Example 1 - Returning values @@ -76,10 +80,11 @@ MaximumCount: 1 The `if()` function expects the second parameter to be the value to return when the `condition` parameter evaluates to `true`. This parameter may be a literal value or an expression that -evaluates to a string, integer, boolean, object, or array value. +evaluates to a string, integer, object, or array value. Boolean and null values aren't +accepted for this parameter. ```yaml -Type: [string, int, bool, object, array] +Type: [string, int, object, array] Required: true MinimumCount: 1 MaximumCount: 1 @@ -89,10 +94,11 @@ MaximumCount: 1 The `if()` function expects the third parameter to be the value to return when the `condition` parameter evaluates to `false`. This parameter may be a literal value or an expression that -evaluates to a string, integer, boolean, object, or array value. +evaluates to a string, integer, object, or array value. Boolean and null values aren't +accepted for this parameter. ```yaml -Type: [string, int, bool, object, array] +Type: [string, int, object, array] Required: true MinimumCount: 1 MaximumCount: 1 @@ -104,7 +110,17 @@ The function returns either the `trueValue` or `falseValue` depending on whether parameter evaluates to `true` or `false`. ```yaml -Type: [string, int, bool, object, array] +Type: [string, int, object, array] ``` +## Error conditions + +DSC raises an error when the `trueValue` or `falseValue` parameter is a boolean or null value. +For example, the expression `[if(true(), true(), false())]` fails with the error +`Function 'if' does not accept boolean arguments, accepted types are: String, Number, Array, +Object`. + +To return a boolean value based on a condition, use the condition expression directly instead of +wrapping it in `if()`. + diff --git a/docs/reference/schemas/config/functions/indexOf.md b/docs/reference/schemas/config/functions/indexOf.md index 76a9adb2c..95fbf5f9e 100644 --- a/docs/reference/schemas/config/functions/indexOf.md +++ b/docs/reference/schemas/config/functions/indexOf.md @@ -1,6 +1,6 @@ --- description: Reference for the 'indexOf' DSC configuration document function -ms.date: 08/12/2025 +ms.date: 09/01/2026 ms.topic: reference title: indexOf --- @@ -27,7 +27,7 @@ in arrays or checking if an item exists without throwing errors. The function performs strict equality checking: - **Strings**: Case-sensitive exact match -- **Numbers**: Numeric equality comparison +- **Numbers**: Numeric equality comparison - **Arrays**: Deep equality (same length, order, and element values) - **Objects**: Deep equality (same keys, values, and structure) @@ -94,7 +94,8 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - hasFeature: "[indexOf(array(createObject('name','Beta')), createObject('name','Beta'))]" + hasFeature: >- + [indexOf(array(createObject('name','Beta')), createObject('name','Beta'))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/intersection.md b/docs/reference/schemas/config/functions/intersection.md index 5e2066772..5aeb1dad8 100644 --- a/docs/reference/schemas/config/functions/intersection.md +++ b/docs/reference/schemas/config/functions/intersection.md @@ -1,10 +1,12 @@ --- description: Reference for the 'intersection' DSC configuration document function -ms.date: 09/26/2025 +ms.date: 09/01/2026 ms.topic: reference title: intersection --- +# intersection + ## Synopsis Returns a single array or object with the common elements from the parameters. @@ -47,8 +49,13 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - commonGroups: "[intersection(createArray('admin-access', 'monitoring', 'backup'), createArray('monitoring', 'backup', 'web-access'), createArray('backup', 'monitoring', 'database'))]" - twoEnvCommon: "[intersection(createArray('admin-access', 'monitoring'), createArray('monitoring', 'audit-log'))]" + commonGroups: >- + [intersection(createArray('admin-access', 'monitoring', 'backup'), + createArray('monitoring', 'backup', 'web-access'), + createArray('backup', 'monitoring', 'database'))] + twoEnvCommon: >- + [intersection(createArray('admin-access', 'monitoring'), + createArray('monitoring', 'audit-log'))] ``` ```bash @@ -86,7 +93,10 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - commonSettings: "[intersection(createObject('timeout', 30, 'retries', 3, 'region', 'us-east'), createObject('retries', 3, 'ssl', true, 'region', 'us-east'), createObject('region', 'us-east', 'retries', 3, 'logging', 'info'))]" + commonSettings: >- + [intersection(createObject('timeout', 30, 'retries', 3, 'region', 'us-east'), + createObject('retries', 3, 'ssl', true, 'region', 'us-east'), + createObject('region', 'us-east', 'retries', 3, 'logging', 'info'))] ``` ```bash @@ -101,8 +111,8 @@ results: actualState: output: commonSettings: - region: us-east retries: 3 + region: us-east messages: [] hadErrors: false ``` @@ -121,8 +131,12 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - noOverlap: "[intersection(createArray('windows-iis', 'dotnet-core'), createArray('linux-apache', 'php', 'mysql'))]" - someOverlap: "[intersection(createArray('docker', 'kubernetes', 'monitoring'), createArray('monitoring', 'logging', 'docker'))]" + noOverlap: >- + [intersection(createArray('windows-iis', 'dotnet-core'), + createArray('linux-apache', 'php', 'mysql'))] + someOverlap: >- + [intersection(createArray('docker', 'kubernetes', 'monitoring'), + createArray('monitoring', 'logging', 'docker'))] ``` ```bash @@ -158,7 +172,10 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - sharedCompliance: "[intersection(createObject('encryption', true, 'backup', 'daily', 'audit', true), createObject('audit', true, 'encryption', true, 'access', 'restricted'), createObject('encryption', true, 'audit', true, 'monitoring', 'enabled'))]" + sharedCompliance: >- + [intersection(createObject('encryption', true, 'backup', 'daily', 'audit', true), + createObject('audit', true, 'encryption', true, 'access', 'restricted'), + createObject('encryption', true, 'audit', true, 'monitoring', 'enabled'))] ``` ```bash @@ -173,8 +190,8 @@ results: actualState: output: sharedCompliance: - audit: true encryption: true + audit: true messages: [] hadErrors: false ``` diff --git a/docs/reference/schemas/config/functions/items.md b/docs/reference/schemas/config/functions/items.md index 3eabd1544..da3d0b735 100644 --- a/docs/reference/schemas/config/functions/items.md +++ b/docs/reference/schemas/config/functions/items.md @@ -1,10 +1,12 @@ --- description: Reference for the 'items' DSC configuration document function -ms.date: 10/11/2025 +ms.date: 09/01/2026 ms.topic: reference title: items --- +# items + ## Synopsis Converts a dictionary object to an array of key-value pairs. diff --git a/docs/reference/schemas/config/functions/join.md b/docs/reference/schemas/config/functions/join.md index 51b96042b..3a84716e2 100644 --- a/docs/reference/schemas/config/functions/join.md +++ b/docs/reference/schemas/config/functions/join.md @@ -1,10 +1,12 @@ --- description: Reference for the 'join' DSC configuration document function -ms.date: 08/29/2025 +ms.date: 09/01/2026 ms.topic: reference title: join --- +# join + ## Synopsis Joins an array into a single string, separated using a delimiter. @@ -12,17 +14,18 @@ Joins an array into a single string, separated using a delimiter. ## Syntax ```Syntax -join(inputArray, delimiter) +join(, ) ``` ## Description The `join()` function takes an array and a delimiter. -- Each array element is converted to a string and concatenated with the - delimiter between elements. +- Each string, number, or boolean element is converted to a string and + concatenated with the delimiter between elements. +- DSC raises an error when an element is null, an array, or an object. -The `delimiter` can be any value; it’s converted to a string. +The `delimiter` must be a string. ## Examples @@ -89,7 +92,7 @@ hadErrors: false ### Example 3 - Format a version string from numeric parts -Convert version components (numbers) into a dotted version string. Non-string +Convert version components (numbers) into a dotted version string. Number elements are converted to strings automatically. ```yaml @@ -131,10 +134,10 @@ Position: 1 ### delimiter -Any value used between elements. Converted to a string. +The string to insert between elements. DSC raises an error when the delimiter isn't a string. ```yaml -Type: any +Type: string Required: true Position: 2 ``` diff --git a/docs/reference/schemas/config/functions/json.md b/docs/reference/schemas/config/functions/json.md index 98bbfdcd4..bf9550393 100644 --- a/docs/reference/schemas/config/functions/json.md +++ b/docs/reference/schemas/config/functions/json.md @@ -1,10 +1,12 @@ --- description: Reference for the 'json' DSC configuration document function -ms.date: 10/11/2025 +ms.date: 09/01/2026 ms.topic: reference title: json --- +# json + ## Synopsis Converts a valid JSON string into a JSON data type. @@ -12,7 +14,7 @@ Converts a valid JSON string into a JSON data type. ## Syntax ```Syntax -json(arg1) +json() ``` ## Description @@ -100,7 +102,8 @@ resources: - name: Echo type: Microsoft.DSC.Debug/Echo properties: - output: "[json('{\"users\":[{\"name\":\"Alice\"},{\"name\":\"Bob\"}]}').users[0].name]" + output: >- + [json('{"users":[{"name":"Alice"},{"name":"Bob"}]}').users[0].name] ``` ```bash @@ -222,6 +225,11 @@ Returns the parsed JSON value. The type depends on the JSON content: Type: object | array | string | number | boolean | null ``` +> [!NOTE] +> The function metadata that the `dsc function list` command reports for `json()` doesn't include +> null in the return types. Parsing the JSON literal `null` still returns a null value, so +> `[json('null')]` evaluates to `null`. + ## Related functions - [`length()`][00] - Returns the length of an array or object diff --git a/docs/reference/schemas/config/functions/lambda.md b/docs/reference/schemas/config/functions/lambda.md new file mode 100644 index 000000000..400d68831 --- /dev/null +++ b/docs/reference/schemas/config/functions/lambda.md @@ -0,0 +1,280 @@ +--- +description: Reference for the 'lambda' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: lambda +--- + +# lambda + +## Synopsis + +Creates a lambda function with named parameters and a body expression for use with functions that +evaluate an expression for each element of an array, like `map()` and `filter()`. + +## Syntax + +```Syntax +lambda(, ) +lambda(, , ) +``` + +## Description + +The `lambda()` function creates an anonymous function, called a _lambda_, that DSC evaluates once +for each element of an array. The result of `lambda()` is only usable as an argument to a function +that accepts lambdas. Currently, those functions are [`map()`][00] and [`filter()`][01]. + +A lambda consists of: + +- One or more _parameter names_, specified as string literals. When `map()` or `filter()` + evaluates the lambda for an element, DSC binds the element to the first parameter and the + zero-based index of the element to the second parameter, if the lambda declares one. +- A _body_, specified as the last argument. The body must be an expression, which is a call to a + configuration function, optionally followed by property or index access. A literal string, + number, or boolean isn't a valid body. + +DSC doesn't evaluate the body when it processes `lambda()`. Instead, DSC stores the parameter +names and the body expression and evaluates the body separately for every element when the +consuming function runs. Inside the body, use [`lambdaVariables()`][02] to read the value that DSC +bound to a parameter. The body can also call any other configuration function, including +[`parameters()`][03] and [`variables()`][04]. + +The `lambda()` function itself accepts any number of parameter names, but `map()` and `filter()` +only accept lambdas with one or two parameters. A lambda with more than two parameters raises an +error when one of those functions uses it. + +## Examples + +### Example 1 - Lambda with a single parameter + +The following example creates a lambda with one parameter, `x`, and passes it to [`map()`][00]. +For each element in the array, DSC binds the element to `x` and evaluates the body, which +multiplies the value by `10` with [`mul()`][05]. + +```yaml +# lambda.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[map(createArray(1, 2, 3), lambda('x', mul(lambdaVariables('x'), 10)))]" +``` + +```bash +dsc config get --file lambda.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - 10 + - 20 + - 30 +messages: [] +hadErrors: false +``` + +### Example 2 - Lambda with an element and index parameter + +The following example creates a lambda with two parameters and passes it to [`filter()`][01]. +DSC binds each element to `item` and the zero-based index of the element to `index`. The body +uses [`mod()`][06] and [`equals()`][07] to return `true` only for elements at even indexes. + +```yaml +# lambda.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [filter( + createArray('a', 'b', 'c', 'd'), + lambda('item', 'index', equals(mod(lambdaVariables('index'), 2), 0)) + )] +``` + +```bash +dsc config get --file lambda.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - a + - c +messages: [] +hadErrors: false +``` + +In this example, the lambda declares the `item` parameter but only uses `index` in its body. The +first parameter is always bound to the element, so you must declare it even when the body only +needs the index. + +### Example 3 - Lambda body that reads a configuration parameter + +The following example shows that a lambda body can use other configuration functions. The body +calls [`parameters()`][03] to read the `prefix` parameter and [`concat()`][08] to combine it with +the current element. + +```yaml +# lambda.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + prefix: + type: string + defaultValue: srv- + names: + type: array + defaultValue: [web, db] +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [map( + parameters('names'), + lambda('name', concat(parameters('prefix'), lambdaVariables('name'))) + )] +``` + +```bash +dsc config get --file lambda.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - srv-web + - srv-db +messages: [] +hadErrors: false +``` + +## Parameters + +### elementName + +The name of the parameter that DSC binds to the current element of the array. The name must be a +string literal, like `'x'`. An expression that returns a string, like `string('x')`, isn't +accepted. + +```yaml +Type: string +Required: true +Position: 1 +``` + +### indexName + +The name of the parameter that DSC binds to the zero-based index of the current element. The name +must be a string literal. When you specify this parameter, the body must be the third argument. + +```yaml +Type: string +Required: false +Position: 2 +``` + +### body + +The expression to evaluate for each element. The body must be a call to a configuration function, +like `mul(lambdaVariables('x'), 2)`. Use [`lambdaVariables()`][02] inside the body to read the +values bound to the lambda's parameters. + +The consuming function determines how it uses the value the body returns. [`map()`][00] collects +the returned values into the output array. [`filter()`][01] requires the body to return a boolean +value and keeps the element when the value is `true`. + +The body is always the last argument. Its position is `2` when the lambda declares one parameter +and `3` when the lambda declares two parameters. + +```yaml +Type: expression +Required: true +Position: last +``` + +## Output + +Returns a lambda value that can only be used as an argument to a function that accepts lambdas. +DSC represents the lambda as an opaque identifier string with the prefix `__lambda_`. If you use +`lambda()` where DSC doesn't expect a lambda, like directly as the value of a resource property, +the result is that identifier string, which isn't useful on its own. + +```yaml +Type: lambda +``` + +## Error conditions + +The function raises an error in the following cases: + +- **Missing arguments**: The function is called with fewer than two arguments. DSC raises + `lambda() requires at least one parameter name and a body expression`. +- **Parameter name isn't a string literal**: A parameter name is a number, a boolean, or an + expression. DSC raises `lambda() parameter names must be string literals`. +- **Body isn't an expression**: The last argument is a literal value instead of a function call. + DSC raises `lambda() body must be an expression`. +- **Passed to a function that doesn't accept lambdas**: The lambda is used as an argument to a + function other than `map()` or `filter()`. For example, `concat('a', lambda('x', ...))` raises + `Function 'concat' does not accept lambda arguments, accepted types are: String, Array`. +- **Too many parameters**: The lambda declares more than two parameters and is passed to `map()` + or `filter()`. For example, DSC raises + `Function 'map' requires lambda with 1 or 2 parameters (element and optional index)`. + +## Notes + +- The output of `dsc function list lambda` reports `minArgs` and `maxArgs` as `0` and an empty + `acceptedArgOrderedTypes` list. This is because DSC's expression parser handles `lambda()` + specially: it passes the arguments to the function without evaluating them first, which is how + the body expression is captured instead of being evaluated immediately. The `constraints` field + in the same output describes the actual requirement: + `Lambda function must have at least one parameter and a body expression`. +- Parameter names are case-sensitive. The name you pass to [`lambdaVariables()`][02] must match + the declared name exactly. +- Lambda parameters are separate from configuration variables and parameters. Declaring a lambda + parameter with the same name as a configuration variable doesn't affect the variable, and + [`variables()`][04] can't read a lambda parameter. +- DSC stores lambdas only for the duration of a single configuration evaluation. +- Only functions that declare a `lambda` argument type accept the result of `lambda()`. To see + which argument types a function accepts, use `dsc function list `. + +## Related functions + +- [`map()`][00] - Transforms every element of an array with a lambda +- [`filter()`][01] - Keeps only the elements of an array for which a lambda returns `true` +- [`lambdaVariables()`][02] - Reads a lambda parameter inside the lambda body +- [`parameters()`][03] - Returns the value of a configuration parameter +- [`variables()`][04] - Returns the value of a configuration variable +- [`mul()`][05] - Multiplies two integers +- [`mod()`][06] - Returns the remainder of dividing two integers +- [`equals()`][07] - Compares two values for equality +- [`concat()`][08] - Combines strings or arrays +- [`createArray()`][09] - Creates an array from values + + +[00]: ./map.md +[01]: ./filter.md +[02]: ./lambdaVariables.md +[03]: ./parameters.md +[04]: ./variables.md +[05]: ./mul.md +[06]: ./mod.md +[07]: ./equals.md +[08]: ./concat.md +[09]: ./createArray.md diff --git a/docs/reference/schemas/config/functions/lambdaVariables.md b/docs/reference/schemas/config/functions/lambdaVariables.md new file mode 100644 index 000000000..8763ad158 --- /dev/null +++ b/docs/reference/schemas/config/functions/lambdaVariables.md @@ -0,0 +1,240 @@ +--- +description: Reference for the 'lambdaVariables' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: lambdaVariables +--- + +# lambdaVariables + +## Synopsis + +Returns the value bound to a named parameter of the lambda function that DSC is currently +evaluating. + +## Syntax + +```Syntax +lambdaVariables() +``` + +## Description + +The `lambdaVariables()` function retrieves the value of a lambda parameter. It's only meaningful +inside the body of a lambda created with [`lambda()`][00]. When [`map()`][01] or [`filter()`][02] +evaluates the lambda for an element, DSC binds the element to the lambda's first parameter and the +zero-based index of the element to the optional second parameter. The `lambdaVariables()` function +returns those bound values by name. + +The returned value has whatever type the bound value has. The element can be of any type, and the +index is always a number. When the returned value is an object or an array, you can use the +property and index access syntax on the result, like `lambdaVariables('server').name` or +`lambdaVariables('server').ports[0]`. + +Lambda parameters are separate from configuration variables and parameters. The +[`variables()`][03] function can't read a lambda parameter, and `lambdaVariables()` can't read a +configuration variable. + +If the name doesn't match a parameter of the lambda that DSC is currently evaluating, including +when you use `lambdaVariables()` outside of a lambda body, DSC raises an error and stops +processing the configuration document. + +## Examples + +### Example 1 - Read the current element + +The following example uses `lambdaVariables()` to read the element that DSC bound to the `x` +parameter and adds `1` to it with [`add()`][04]. + +```yaml +# lambdaVariables.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[map(createArray(1, 2, 3), lambda('x', add(lambdaVariables('x'), 1)))]" +``` + +```bash +dsc config get --file lambdaVariables.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - 2 + - 3 + - 4 +messages: [] +hadErrors: false +``` + +### Example 2 - Read the element and its index + +The following example declares two lambda parameters. DSC binds each element to `color` and the +zero-based index of the element to `position`. The body reads both values with +`lambdaVariables()` and combines them into an object with [`createObject()`][05]. + +```yaml +# lambdaVariables.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [map( + createArray('red', 'green', 'blue'), + lambda( + 'color', + 'position', + createObject( + 'position', lambdaVariables('position'), + 'color', lambdaVariables('color') + ) + ) + )] +``` + +```bash +dsc config get --file lambdaVariables.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - position: 0 + color: red + - position: 1 + color: green + - position: 2 + color: blue +messages: [] +hadErrors: false +``` + +### Example 3 - Access properties of an object element + +The following example maps an array of objects. The body uses the property access syntax on the +result of `lambdaVariables()` to read the `name` property and the first item of the `ports` array +for each element, then combines them with [`format()`][06]. + +```yaml +# lambdaVariables.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + servers: + type: array + defaultValue: + - name: web01 + ports: [80, 443] + - name: db01 + ports: [5432] +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [map( + parameters('servers'), + lambda( + 'server', + format( + '{0}:{1}', + lambdaVariables('server').name, + lambdaVariables('server').ports[0] + ) + ) + )] +``` + +```bash +dsc config get --file lambdaVariables.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - web01:80 + - db01:5432 +messages: [] +hadErrors: false +``` + +## Parameters + +### name + +The name of the lambda parameter to read. The name is case-sensitive and must exactly match one of +the parameter names declared in the enclosing [`lambda()`][00] call. + +```yaml +Type: string +Required: true +Position: 1 +``` + +## Output + +Returns the value that DSC bound to the named parameter for the current element. For the first +lambda parameter, the value is the element itself and can be of any type. For the optional second +lambda parameter, the value is the zero-based index of the element as a number. + +```yaml +Type: [array, boolean, null, number, object, string] +``` + +## Error conditions + +The function raises an error in the following cases: + +- **Unknown parameter**: The name doesn't match a parameter of the lambda that DSC is currently + evaluating. DSC raises `Lambda parameter '' not found in current context`. +- **Used outside a lambda**: The function is called outside of a lambda body, so no lambda + parameters are bound. DSC raises the same + `Lambda parameter '' not found in current context` error. +- **Invalid name**: The argument isn't a string. + +## Notes + +- Parameter names are case-sensitive. +- The index bound to the optional second lambda parameter is a zero-based number. +- DSC binds the lambda parameters fresh for every element. The body can't read the values bound + for other elements of the array. +- Lambda parameters are separate from the values returned by [`variables()`][03] and + [`parameters()`][07]. You can still call those functions inside a lambda body to read + configuration variables and parameters. + +## Related functions + +- [`lambda()`][00] - Creates a lambda function with named parameters +- [`map()`][01] - Transforms every element of an array with a lambda +- [`filter()`][02] - Keeps only the elements of an array for which a lambda returns `true` +- [`variables()`][03] - Returns the value of a configuration variable +- [`parameters()`][07] - Returns the value of a configuration parameter +- [`add()`][04] - Adds two integers +- [`createObject()`][05] - Creates an object from key-value pairs +- [`format()`][06] - Creates a formatted string from input values + + +[00]: ./lambda.md +[01]: ./map.md +[02]: ./filter.md +[03]: ./variables.md +[04]: ./add.md +[05]: ./createObject.md +[06]: ./format.md +[07]: ./parameters.md diff --git a/docs/reference/schemas/config/functions/last.md b/docs/reference/schemas/config/functions/last.md index 595e8ede9..5989505b5 100644 --- a/docs/reference/schemas/config/functions/last.md +++ b/docs/reference/schemas/config/functions/last.md @@ -1,10 +1,12 @@ --- description: Reference for the 'last' DSC configuration document function -ms.date: 01/25/2025 +ms.date: 09/01/2026 ms.topic: reference title: last --- +# last + ## Synopsis Returns the last element of an array, or the last character of a string. diff --git a/docs/reference/schemas/config/functions/lastIndexOf.md b/docs/reference/schemas/config/functions/lastIndexOf.md index 666c88c70..407efc52f 100644 --- a/docs/reference/schemas/config/functions/lastIndexOf.md +++ b/docs/reference/schemas/config/functions/lastIndexOf.md @@ -1,10 +1,12 @@ --- description: Reference for the 'lastIndexOf' DSC configuration document function -ms.date: 08/29/2025 +ms.date: 09/01/2026 ms.topic: reference title: lastIndexOf --- +# lastIndexOf + ## Synopsis Returns an integer for the index of the last occurrence of an item in an array. @@ -47,8 +49,10 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - lastWebIndex: "[lastIndexOf(createArray('web01','db01','web02','cache01','web03'), 'web03')]" - lastWebFamilyIndex: "[lastIndexOf(createArray('web01','db01','web02','cache01','web02'), 'web02')]" + lastWebIndex: >- + [lastIndexOf(createArray('web01','db01','web02','cache01','web03'), 'web03')] + lastWebFamilyIndex: >- + [lastIndexOf(createArray('web01','db01','web02','cache01','web02'), 'web02')] ``` ```bash @@ -86,7 +90,10 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - lastBetaIndex: "[lastIndexOf(createArray(createObject('name','Beta'), createObject('name','Gamma'), createObject('name','Beta')), createObject('name','Beta'))]" + lastBetaIndex: >- + [lastIndexOf(createArray(createObject('name','Beta'), + createObject('name','Gamma'), createObject('name','Beta')), + createObject('name','Beta'))] ``` ```bash @@ -105,8 +112,9 @@ messages: [] hadErrors: false ``` -Property order in objects doesn't matter. The following also returns `1` due to -deep equality: `lastIndexOf(array(createObject('a',1,'b',2), createObject('b',2,'a',1)), createObject('a',1,'b',2))`. +Property order in objects doesn't matter. The following also returns `1` due to deep equality: +`lastIndexOf(array(createObject('a',1,'b',2), createObject('b',2,'a',1)), +createObject('a',1,'b',2))`. ## Parameters diff --git a/docs/reference/schemas/config/functions/length.md b/docs/reference/schemas/config/functions/length.md index fee7f77c2..3b33c608a 100644 --- a/docs/reference/schemas/config/functions/length.md +++ b/docs/reference/schemas/config/functions/length.md @@ -1,6 +1,6 @@ --- description: Reference for the 'length' DSC configuration document function -ms.date: 08/08/2025 +ms.date: 09/01/2026 ms.topic: reference title: length --- @@ -136,7 +136,9 @@ parameters: defaultValue: "Hello DSC!" longText: type: string - defaultValue: "This is a longer string with more characters to demonstrate length calculation." + defaultValue: >- + This is a longer string with more characters to demonstrate length + calculation. resources: - name: Check string lengths type: Microsoft.DSC.Debug/Echo @@ -160,7 +162,7 @@ results: actualState: output: messageLength: 10 - longTextLength: 78 + longTextLength: 79 emptyStringLength: 0 literalLength: 3 messages: [] diff --git a/docs/reference/schemas/config/functions/less.md b/docs/reference/schemas/config/functions/less.md index 8c04bab85..7acc871f6 100644 --- a/docs/reference/schemas/config/functions/less.md +++ b/docs/reference/schemas/config/functions/less.md @@ -1,6 +1,6 @@ --- description: Reference for the 'less' DSC configuration document function -ms.date: 07/24/2025 +ms.date: 09/01/2026 ms.topic: reference title: less --- @@ -24,7 +24,8 @@ returning `true` if it is and otherwise `false`. You can use this function to co two values of the same data type. If the values are different types, like a string and an integer, DSC returns an error for this function. -For strings, the comparison is case-sensitive and uses lexicographic ordering based on character codes. +For strings, the comparison is case-sensitive and uses lexicographic ordering based on character +codes. ## Examples @@ -39,7 +40,7 @@ resources: - name: Compare numbers type: Microsoft.DSC.Debug/Echo properties: - output: + output: firstLess: "[less(3, 5)]" secondLess: "[less(5, 3)]" equalNumbers: "[less(5, 5)]" diff --git a/docs/reference/schemas/config/functions/lessOrEquals.md b/docs/reference/schemas/config/functions/lessOrEquals.md index 96a444c70..1e65cbe3d 100644 --- a/docs/reference/schemas/config/functions/lessOrEquals.md +++ b/docs/reference/schemas/config/functions/lessOrEquals.md @@ -1,6 +1,6 @@ --- description: Reference for the 'lessOrEquals' DSC configuration document function -ms.date: 07/24/2025 +ms.date: 09/01/2026 ms.topic: reference title: lessOrEquals --- @@ -41,7 +41,7 @@ resources: - name: Compare numbers type: Microsoft.DSC.Debug/Echo properties: - output: + output: firstLess: "[lessOrEquals(3, 5)]" secondLess: "[lessOrEquals(5, 3)]" equalNumbers: "[lessOrEquals(5, 5)]" diff --git a/docs/reference/schemas/config/functions/map.md b/docs/reference/schemas/config/functions/map.md new file mode 100644 index 000000000..ca240e3e3 --- /dev/null +++ b/docs/reference/schemas/config/functions/map.md @@ -0,0 +1,313 @@ +--- +description: Reference for the 'map' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: map +--- + +# map + +## Synopsis + +Transforms an array by applying a lambda function to each element and returning the results as a +new array. + +## Syntax + +```Syntax +map(, ) +``` + +## Description + +The `map()` function evaluates a lambda function created with [`lambda()`][00] against every +element of an array and returns a new array that contains the value the lambda returned for each +element. The output array always has the same number of elements as the input array, in the same +order. + +For each element in the input array, DSC: + +1. Binds the element to the lambda's first parameter. +1. Binds the zero-based index of the element to the lambda's second parameter, if the lambda + declares one. +1. Evaluates the lambda's body expression. Inside the body, use [`lambdaVariables()`][01] to read + the bound parameters. +1. Appends the value the body returned to the output array. + +Unlike [`filter()`][02], the lambda body can return a value of any type. The returned values +don't need to have the same type as the input elements, so you can use `map()` to convert an array +of numbers into an array of strings, an array of objects into an array of one of their properties, +or an array of values into an array of objects. + +The lambda body can call any other configuration function. DSC evaluates the body with a copy of +the current context, so the body can read configuration [`parameters()`][03] and +[`variables()`][04] in addition to the lambda's own parameters. + +This function is useful for: + +- Applying the same calculation or formatting to every element of an array. +- Extracting a single property from every object in an array. +- Building an array of objects from an array of simple values. +- Generating sequential names or values together with [`range()`][05]. + +## Examples + +### Example 1 - Multiply every element + +The following example multiplies every number in the `numbers` parameter by `2`. The lambda +declares a single parameter, `x`, which DSC binds to each element in turn. + +```yaml +# map.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + numbers: + type: array + defaultValue: [1, 2, 3] +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[map(parameters('numbers'), lambda('x', mul(lambdaVariables('x'), 2)))]" +``` + +```bash +dsc config get --file map.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - 2 + - 4 + - 6 +messages: [] +hadErrors: false +``` + +### Example 2 - Use the element index + +The following example uses a lambda with two parameters. DSC binds the element to `val` and the +zero-based index of the element to `i`. The lambda adds the two values together. + +```yaml +# map.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + items: + type: array + defaultValue: [10, 20, 30] +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [map( + parameters('items'), + lambda('val', 'i', add(lambdaVariables('val'), lambdaVariables('i'))) + )] +``` + +```bash +dsc config get --file map.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - 10 + - 21 + - 32 +messages: [] +hadErrors: false +``` + +### Example 3 - Generate names from a range + +The following example combines `map()` with [`range()`][05] and [`format()`][06] to generate a +sequence of server names. The input elements are numbers and the output elements are strings. + +```yaml +# map.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[map(range(1, 3), lambda('n', format('server-{0}', lambdaVariables('n'))))]" +``` + +```bash +dsc config get --file map.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - server-1 + - server-2 + - server-3 +messages: [] +hadErrors: false +``` + +### Example 4 - Extract and reshape object properties + +The following example maps an array of objects twice. The `names` output extracts the `name` +property of every object with the property access syntax. The `summary` output uses +[`createObject()`][07] to build a new object for every element from its index and its properties. + +```yaml +# map.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + users: + type: array + defaultValue: + - name: alice + role: admin + - name: bob + role: user +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: + names: "[map(parameters('users'), lambda('user', lambdaVariables('user').name))]" + summary: >- + [map( + parameters('users'), + lambda( + 'user', + 'index', + createObject( + 'id', lambdaVariables('index'), + 'label', format( + '{0} ({1})', + lambdaVariables('user').name, + lambdaVariables('user').role + ) + ) + ) + )] +``` + +```bash +dsc config get --file map.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + names: + - alice + - bob + summary: + - id: 0 + label: alice (admin) + - id: 1 + label: bob (user) +messages: [] +hadErrors: false +``` + +## Parameters + +### inputArray + +The array whose elements to transform. The elements can be of any type, including objects and +nested arrays. + +```yaml +Type: array +Required: true +Position: 1 +``` + +### lambda + +A lambda function created with [`lambda()`][00]. The lambda must declare one or two parameters. +DSC binds the current element to the first parameter and the zero-based index of the element to +the optional second parameter. The value the lambda's body returns becomes the corresponding +element of the output array. + +```yaml +Type: lambda +Required: true +Position: 2 +``` + +## Output + +Returns an array with one element for each element of `inputArray`, in the same order. Each +element is the value the lambda returned for the corresponding input element. Returns an empty +array when `inputArray` is empty. + +```yaml +Type: array +``` + +## Error conditions + +The function raises an error in the following cases: + +- **Not an array**: The first argument isn't an array. For example, passing a string raises + `Function 'map' does not accept string arguments, accepted types are: Array`. +- **Not a lambda**: The second argument isn't a lambda created with [`lambda()`][00]. +- **Too many parameters**: The lambda declares more than two parameters. DSC raises + `Function 'map' requires lambda with 1 or 2 parameters (element and optional index)`. +- **Body error**: The lambda body raises an error. For example, calling + [`lambdaVariables()`][01] with a name that the lambda didn't declare raises + `Lambda parameter '' not found in current context`. + +## Notes + +- The function always returns an array with the same length as the input array. To remove + elements from an array, use [`filter()`][02] instead. +- The function evaluates the lambda body once for each element in the input array. When the input + array is empty, the body is never evaluated and the function returns an empty array. +- The index that DSC binds to the optional second parameter is a zero-based number. +- The lambda body can return a value of any type, including objects and arrays. +- Lambda parameters are separate from configuration variables. Read them with + [`lambdaVariables()`][01], not [`variables()`][04]. + +## Related functions + +- [`lambda()`][00] - Creates the lambda function that `map()` evaluates +- [`lambdaVariables()`][01] - Reads a lambda parameter inside the lambda body +- [`filter()`][02] - Keeps only the elements of an array for which a lambda returns `true` +- [`parameters()`][03] - Returns the value of a configuration parameter +- [`variables()`][04] - Returns the value of a configuration variable +- [`range()`][05] - Creates an array of sequential integers +- [`format()`][06] - Creates a formatted string from input values +- [`createObject()`][07] - Creates an object from key-value pairs +- [`mul()`][08] - Multiplies two integers +- [`add()`][09] - Adds two integers + + +[00]: ./lambda.md +[01]: ./lambdaVariables.md +[02]: ./filter.md +[03]: ./parameters.md +[04]: ./variables.md +[05]: ./range.md +[06]: ./format.md +[07]: ./createObject.md +[08]: ./mul.md +[09]: ./add.md diff --git a/docs/reference/schemas/config/functions/mul.md b/docs/reference/schemas/config/functions/mul.md index 68e7ad280..aeb36c392 100644 --- a/docs/reference/schemas/config/functions/mul.md +++ b/docs/reference/schemas/config/functions/mul.md @@ -1,6 +1,6 @@ --- description: Reference for the 'mul' DSC configuration document function -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: mul --- @@ -19,8 +19,8 @@ mul() ## Description -The `mul()` function returns the product of multiplying two integers. It multiplies the first operand -by the second operand. You can nest calls to `mul()` to multiply more than two integers. +The `mul()` function returns the product of multiplying two integers. It multiplies the first +operand by the second operand. You can nest calls to `mul()` to multiply more than two integers. ## Examples @@ -35,11 +35,11 @@ resources: - name: Multiplying integers type: Microsoft.DSC.Debug/Echo properties: - output: "[mul(3, 5)]" + output: "[mul(3, 5)]" ``` ```bash -dsc config get --file mul.example.1.dsc.config.yaml config get +dsc config get --file mul.example.1.dsc.config.yaml ``` ```yaml @@ -86,9 +86,9 @@ hadErrors: false ### operands -The `mul()` function expects exactly two integers as input. The **operands** can be either an integer -or the output of any configuration function that returns an integer. The function divides the first -operand by the second operand. Separate the **operands** with a comma (`,`). +The `mul()` function expects exactly two integers as input. The **operands** can be either an +integer or the output of any configuration function that returns an integer. The function +multiplies the first operand by the second operand. Separate the **operands** with a comma (`,`). ```yaml Type: integer diff --git a/docs/reference/schemas/config/functions/null.md b/docs/reference/schemas/config/functions/null.md index 5de697414..9b1ffee50 100644 --- a/docs/reference/schemas/config/functions/null.md +++ b/docs/reference/schemas/config/functions/null.md @@ -1,6 +1,6 @@ --- description: Reference for the 'null' DSC configuration document function -ms.date: 07/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: null --- @@ -136,7 +136,8 @@ Type: null - The `null()` function is particularly useful when working with other functions that handle null values, such as `coalesce()`. - Unlike undefined or missing values, `null()` explicitly represents the JSON null value. -- When used in object creation with `createObject()`, null properties are included in the resulting object. +- When used in object creation with `createObject()`, null properties are included in the + resulting object. - The function takes no arguments and will return an error if any arguments are provided. ## Related functions diff --git a/docs/reference/schemas/config/functions/objectKeys.md b/docs/reference/schemas/config/functions/objectKeys.md index 6f3e4e5c0..bf516d696 100644 --- a/docs/reference/schemas/config/functions/objectKeys.md +++ b/docs/reference/schemas/config/functions/objectKeys.md @@ -1,10 +1,12 @@ --- description: Reference for the 'objectKeys' DSC configuration document function -ms.date: 11/14/2025 +ms.date: 09/01/2026 ms.topic: reference title: objectKeys --- +# objectKeys + ## Synopsis Returns an array containing all the keys from an object. @@ -44,7 +46,8 @@ resources: - name: Echo type: Microsoft.DSC.Debug/Echo properties: - output: "[objectKeys(createObject('firstName', 'John', 'lastName', 'Doe', 'age', 30))]" + output: >- + [objectKeys(createObject('firstName', 'John', 'lastName', 'Doe', 'age', 30))] ``` ```bash @@ -197,7 +200,9 @@ resources: - name: Echo type: Microsoft.DSC.Debug/Echo properties: - output: "[objectKeys(createObject('user', createObject('name', 'John', 'age', 30), 'role', 'admin'))]" + output: >- + [objectKeys(createObject('user', createObject('name', 'John', 'age', 30), + 'role', 'admin'))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/overview.md b/docs/reference/schemas/config/functions/overview.md index 305e0b85e..d0d9b6ac0 100644 --- a/docs/reference/schemas/config/functions/overview.md +++ b/docs/reference/schemas/config/functions/overview.md @@ -1,6 +1,6 @@ --- description: Reference for available functions in a Desired State Configuration document. -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Configuration document functions reference --- @@ -183,10 +183,10 @@ hadErrors: false ### Example 3 - Using nested functions The following configuration document shows how you can nest functions. The first two resource -instances use the output of the [concat()][concat] function as input to the [base64()][base64] function. -The third resource instance uses the output of the nested functions from the first two instances -as input to the `concat()` function. The last resource instance converts the output of the deeply -nested functions shown in the third instance to base64. +instances use the output of the [concat()][concat] function as input to the [base64()][base64] +function. The third resource instance uses the output of the nested functions from the first two +instances as input to the `concat()` function. The last resource instance converts the output of +the deeply nested functions shown in the third instance to base64. ```yaml # overview.example.3.dsc.config.yaml @@ -296,8 +296,8 @@ parameters: - name: Nested third ``` -The first configuration document defines an instance of the `Microsoft.DSC.Debug/Echo` resource to show how you -can access an object's properties in a configuration document. +The first configuration document defines an instance of the `Microsoft.DSC.Debug/Echo` resource +to show how you can access an object's properties in a configuration document. ```yaml # overview.example.4.properties.dsc.config.yaml @@ -433,7 +433,7 @@ resources: ```sh $params=overview.example.4.dsc.parameters.yaml $config=overview.example.4.items.dsc.config.yaml -dsc config --parameters-file $params get --path $config +dsc config --parameters-file $params get --file $config ``` ```yaml @@ -541,135 +541,184 @@ dsc config --parameters-file $params get --file $config ``` ```yaml -$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json -# Minimal definition of the parameters -parameters: - data: { type: object } - list: { type: array } - -resources: - - name: Access values in complex objects and arrays - type: Microsoft.DSC.Debug/Echo - properties: +results: +- metadata: + Microsoft.DSC: + duration: PT0.0437158S + name: Access values in complex objects and arrays + type: Microsoft.DSC.Debug/Echo + result: + actualState: output: - # Accessing array items of an object property - data.services[0]: "[parameters('data').services[0]]" - data.services[1]: "[parameters('data').services[1]]" - data.services[2]: "[parameters('data').services[2]]" - # Accessing properties of an object in an array - list[2].name: "[parameters('list')[2].name]" - list[2].value: "[parameters('list')[2].value]" - # Accessing the property of an object in a nested array - list[3][2].name: "[parameters('list')[3][2].name]" + data.services[0]: web + data.services[1]: database + data.services[2]: application + list[2].name: third + list[2].value: 3 + list[3][2].name: Nested third ``` ## Functions -The following sections include the available DSC configuration functions by purpose and input type. +The following sections list the available functions grouped by category. The categories are the ones +that the [dsc function list][04] command reports for each function. A function that belongs to more +than one category, like `contains()`, appears in every category it belongs to. -### Array and collection functions +### Array functions -The following list of functions operate on arrays and collections: +The following functions operate on arrays: - [array()][array] - Convert a value into an array containing that value. -- [concat()][concat] - Combine multiple arrays of strings into a single array of strings. +- [concat()][concat] - Combine multiple strings into a single string, or multiple arrays into a + single array. - [contains()][contains] - Check if an array contains a value or an object contains a key. - [createArray()][createArray] - Create an array of a given type from zero or more values of the same type. - [empty()][empty] - Check if a value (string, array, or object) is empty. +- [filter()][filter] - Return a new array containing only the elements of an array for which a + lambda function returns true. - [first()][first] - Return the first element of an array or the first character of a string. - [indexOf()][indexOf] - Return the zero-based index of the first occurrence of a value in an array. -- [intersection()][intersection] - Return a single array or object with the common elements from the parameters. -- [items()][items] - Convert an object into an array of key-value pair objects. -- [join()][join] - Combine array elements into a single string with a specified delimiter. +- [intersection()][intersection] - Return a single array or object with the common elements from the + parameters. - [last()][last] - Return the last element of an array or the last character of a string. -- [lastIndexOf()][lastIndexOf] - Return the zero-based index of the last occurrence of a value in an array. -- [length()][length] - Return the number of elements in an array, characters in a string, or top-level properties in an object. -- [max()][max] - Return the largest integer value from an array of integers. -- [min()][min] - Return the smallest integer value from an array of integers. +- [lastIndexOf()][lastIndexOf] - Return the zero-based index of the last occurrence of a value in an + array. +- [length()][length] - Return the number of elements in an array, characters in a string, or + top-level properties in an object. +- [map()][map] - Transform every element of an array with a lambda function and return the results + as a new array. - [range()][range] - Create an array of integers within a specified range. - [skip()][skip] - Return an array or string with elements skipped from the beginning. - [take()][take] - Return an array or string with the specified number of elements from the start. -- [tryGet()][tryGet] - Safely retrieve a value from an array by index or an object by key without throwing an error. -- [tryIndexFromEnd()][tryIndexFromEnd] - Safely retrieve a value from an array by counting backward from the end. +- [tryGet()][tryGet] - Safely retrieve a value from an array by index or an object by key without + throwing an error. +- [tryIndexFromEnd()][tryIndexFromEnd] - Safely retrieve a value from an array by counting backward + from the end. - [union()][union] - Return a single array or object with all unique elements from the parameters. +### CIDR functions + +The following functions parse and calculate IP address ranges in CIDR notation: + +- [cidrHost()][cidrHost] - Return the usable IP address of the host at a given index within an IP + address range in CIDR notation. +- [cidrSubnet()][cidrSubnet] - Split an IP address range in CIDR notation into subnets and return + the subnet at a given index. +- [parseCidr()][parseCidr] - Parse an IP address range in CIDR notation and return its network + properties. + ### Comparison functions -The following list of functions compare values: +The following functions compare values: +- [coalesce()][coalesce] - Return the first non-null value from the provided arguments. - [equals()][equals] - Check if two values are equal. - [greater()][greater] - Check if the first value is greater than the second value. -- [greaterOrEquals()][greaterOrEquals] - Check if the first value is greater than or equal to the second value. +- [greaterOrEquals()][greaterOrEquals] - Check if the first value is greater than or equal to the + second value. - [less()][less] - Check if the first value is less than the second value. -- [lessOrEquals()][lessOrEquals] - Check if the first value is less than or equal to the second value. +- [lessOrEquals()][lessOrEquals] - Check if the first value is less than or equal to the second + value. + +### Date functions -### Data functions +The following functions work with dates and times: -The following list of functions operate on data outside of a resource instance: +- [utcNow()][utcNow] - Return the current UTC datetime in a specified format. + +### Deployment functions + +The following functions return data about the configuration document and the environment DSC is +processing it in, like parameters, variables, and secrets: - [context()][context] - Return contextual information about the system and execution environment. -- [envvar()][envvar] - Return the value of a specified environment variable. - [parameters()][parameters] - Return the value of a specified configuration parameter. - [secret()][secret] - Retrieve a secret value from a secure store. - [variables()][variables] - Return the value of a specified configuration variable. +### Lambda functions + +The following functions create and use lambda functions, which DSC evaluates once for each element +of an array: + +- [filter()][filter] - Return a new array containing only the elements of an array for which a + lambda function returns true. +- [lambda()][lambda] - Create a lambda function with named parameters and a body expression for use + with `map()` and `filter()`. +- [lambdaVariables()][lambdaVariables] - Return the value bound to a named parameter of the lambda + function currently being evaluated. +- [map()][map] - Transform every element of an array with a lambda function and return the results + as a new array. + ### Logical functions -The following list of functions perform logical operations: +The following functions perform logical operations: - [and()][and] - Return true if all boolean values are true. - [bool()][bool] - Convert a value to a boolean. - [false()][false] - Return the boolean value false. - [if()][if] - Return one of two values based on a boolean condition. - [not()][not] - Return the logical negation of a boolean value. -- [null()][null] - Return a null value. - [or()][or] - Return true if any boolean value is true. - [true()][true] - Return the boolean value true. -### Mathematics functions +### Numeric functions -The following list of functions operate on integer values or arrays of integer values: +The following functions operate on integer values: - [add()][add] - Return the sum of two integers. +- [copyIndex()][copyIndex] - Return the current iteration index of a copy loop. - [div()][div] - Return the dividend of two integers as an integer, dropping the remainder of the result, if any. - [int()][int] - Convert a string or number with a fractional part into an integer. -- [max()][max] - Return the largest value from an array of integers. -- [min()][min] - Return the smallest value from an array of integers. +- [max()][max] - Return the largest integer value from an array of integers. +- [min()][min] - Return the smallest integer value from an array of integers. - [mod()][mod] - Return the remainder from the division of two integers. - [mul()][mul] - Return the product from multiplying two integers. - [sub()][sub] - Return the difference from subtracting one integer from another. +The `copyIndex()` function is only meaningful inside a resource that defines the `copy` property. +The `copy` property isn't a function, but it works together with `copyIndex()` to create multiple +instances of a resource. For more information, see [copy][copy]. + ### Object functions -The following list of functions operate on objects: +The following functions operate on objects: -- [coalesce()][coalesce] - Return the first non-null value from the provided arguments. - [contains()][contains] - Check if an array contains a value or an object contains a key. - [createObject()][createObject] - Create an object from key-value pairs. - [empty()][empty] - Check if a value (string, array, or object) is empty. +- [intersection()][intersection] - Return a single array or object with the common elements from the + parameters. - [items()][items] - Convert an object into an array of key-value pair objects. - [json()][json] - Parse a JSON string and return the resulting value. -- [tryGet()][tryGet] - Safely retrieve a value from an array by index or an object by key without throwing an error. +- [length()][length] - Return the number of elements in an array, characters in a string, or + top-level properties in an object. +- [null()][null] - Return a null value. +- [objectKeys()][objectKeys] - Return an array of the top-level keys of an object. +- [shallowMerge()][shallowMerge] - Combine an array of objects into a single object, merging only + the top-level properties. +- [tryGet()][tryGet] - Safely retrieve a value from an array by index or an object by key without + throwing an error. +- [union()][union] - Return a single array or object with all unique elements from the parameters. ### Resource functions -The following list of functions operate on resource instances: +The following functions operate on resource instances: -- [copyIndex()][copyIndex] - Return the current iteration index of a copy loop. - [reference()][reference] - Return the result data for another resource instance. -- [resourceId()][resourceId] - Return the ID of another resource instance to reference or depend - on. +- [resourceId()][resourceId] - Return the ID of another resource instance to reference or depend on. ### String functions -The following list of functions are for manipulating strings: +The following functions manipulate strings: - [base64()][base64] - Return the base64 representation of a string. -- [base64ToString()][base64ToString] - Decode a base64-encoded string and return the original string. -- [concat()][concat] - Return a combined string where the input strings are concatenated in the - order they're specified. +- [base64ToString()][base64ToString] - Decode a base64-encoded string and return the original + string. +- [concat()][concat] - Combine multiple strings into a single string, or multiple arrays into a + single array. - [contains()][contains] - Check if an array contains a value or an object contains a key. - [dataUri()][dataUri] - Convert a value to a data URI. - [dataUriToString()][dataUriToString] - Convert a data URI formatted value to a string. @@ -677,14 +726,19 @@ The following list of functions are for manipulating strings: - [endsWith()][endsWith] - Check if a string ends with a specified suffix. - [first()][first] - Return the first element of an array or the first character of a string. - [format()][format] - Create a formatted string from input values. +- [indexOf()][indexOf] - Return the zero-based index of the first occurrence of a value in an array. - [join()][join] - Combine array elements into a single string with a specified delimiter. - [last()][last] - Return the last element of an array or the last character of a string. -- [length()][length] - Return the number of elements in an array, characters in a string, or top-level properties in an object. +- [lastIndexOf()][lastIndexOf] - Return the zero-based index of the last occurrence of a value in an + array. +- [length()][length] - Return the number of elements in an array, characters in a string, or + top-level properties in an object. +- [path()][path] - Construct a file system path from one or more path segments. - [skip()][skip] - Return an array or string with elements skipped from the beginning. - [startsWith()][startsWith] - Check if a string starts with a specified prefix. -- [take()][take] - Return an array or string with the specified number of elements from the start. - [string()][string] - Convert a value to its string representation. - [substring()][substring] - Extract a portion of a string starting at a specified position. +- [take()][take] - Return an array or string with the specified number of elements from the start. - [toLower()][toLower] - Convert a string to lowercase. - [toUpper()][toUpper] - Convert a string to uppercase. - [trim()][trim] - Remove leading and trailing whitespace from a string. @@ -695,32 +749,24 @@ The following list of functions are for manipulating strings: ### System functions -The following list of functions provide system-level information: +The following functions return information about the system or the current execution of DSC: -- [path()][path] - Construct a file system path from one or more path segments. +- [envvar()][envvar] - Return the value of a specified environment variable. - [restartRequired()][restartRequired] - Return whether a system, service, or process requires a restart. -- [stateChanged()][stateChanged] - Return whether a resource instance changed state during a - `set` operation. +- [stateChanged()][stateChanged] - Return whether a resource instance changed state during a `set` + operation. +- [stdout()][stdout] - Return the standard output of an extension's `import` command for processing + in the manifest's `output` expression. - [systemRoot()][systemRoot] - Return the system root directory path. -- [utcNow()][utcNow] - Return the current UTC datetime in a specified format. - -### Type functions - -The following list of functions create or convert values of a given type: - -- [array()][array] - Convert a value into an array containing that value. -- [bool()][bool] - Convert a value to a boolean. -- [createArray()][createArray] - Create an array of a given type from zero or more values of the - same type. -- [createObject()][createObject] - Create an object from key-value pairs. -- [int()][int] - Convert a string or number with a fractional part into an integer. -- [string()][string] - Convert a value to its string representation. +- [tryWhich()][tryWhich] - Return the full path to an executable found in the `PATH` environment + variable, or null if it isn't found. [01]: https://yaml.org/spec/1.2.2/#folded-style [02]: https://yaml.org/spec/1.2.2/#literal-style [03]: https://yaml.org/spec/1.2.2/#block-chomping-indicator +[04]: ../../../cli/function/list.md [add]: ./add.md [and]: ./and.md @@ -728,10 +774,13 @@ The following list of functions create or convert values of a given type: [base64]: ./base64.md [base64ToString]: ./base64ToString.md [bool]: ./bool.md +[cidrHost]: ./cidrHost.md +[cidrSubnet]: ./cidrSubnet.md [coalesce]: ./coalesce.md [concat]: ./concat.md [contains]: ./contains.md [context]: ./context.md +[copy]: ./copy.md [copyIndex]: ./copyIndex.md [createArray]: ./createArray.md [createObject]: ./createObject.md @@ -743,6 +792,7 @@ The following list of functions create or convert values of a given type: [envvar]: ./envvar.md [equals]: ./equals.md [false]: ./false.md +[filter]: ./filter.md [first]: ./first.md [format]: ./format.md [greater]: ./greater.md @@ -754,39 +804,47 @@ The following list of functions create or convert values of a given type: [items]: ./items.md [join]: ./join.md [json]: ./json.md +[lambda]: ./lambda.md +[lambdaVariables]: ./lambdaVariables.md [last]: ./last.md [lastIndexOf]: ./lastIndexOf.md [length]: ./length.md [less]: ./less.md [lessOrEquals]: ./lessOrEquals.md +[map]: ./map.md [max]: ./max.md [min]: ./min.md [mod]: ./mod.md [mul]: ./mul.md [not]: ./not.md [null]: ./null.md +[objectKeys]: ./objectKeys.md [or]: ./or.md [parameters]: ./parameters.md +[parseCidr]: ./parseCidr.md [path]: ./path.md [range]: ./range.md [reference]: ./reference.md [resourceId]: ./resourceId.md [restartRequired]: ./restartRequired.md [secret]: ./secret.md +[shallowMerge]: ./shallowMerge.md [skip]: ./skip.md [startsWith]: ./startsWith.md [stateChanged]: ./stateChanged.md +[stdout]: ./stdout.md [string]: ./string.md -[take]: ./take.md [sub]: ./sub.md [substring]: ./substring.md [systemRoot]: ./systemRoot.md +[take]: ./take.md [toLower]: ./toLower.md [toUpper]: ./toUpper.md [trim]: ./trim.md [true]: ./true.md [tryGet]: ./tryGet.md [tryIndexFromEnd]: ./tryIndexFromEnd.md +[tryWhich]: ./tryWhich.md [union]: ./union.md [uniqueString]: ./uniqueString.md [uri]: ./uri.md diff --git a/docs/reference/schemas/config/functions/parameters.md b/docs/reference/schemas/config/functions/parameters.md index 43a313645..e8790caad 100644 --- a/docs/reference/schemas/config/functions/parameters.md +++ b/docs/reference/schemas/config/functions/parameters.md @@ -1,6 +1,6 @@ --- description: Reference for the 'parameters' DSC configuration document function -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: parameters --- @@ -91,7 +91,8 @@ hadErrors: false The `parameters()` function expects a single string as input, representing the name of the parameter to return. If no parameter with the specified name is defined in the configuration -document, DSC raises an error during validation. +document, DSC raises an error during validation. If the parameter is defined without a default +value and you don't provide a value for it, DSC raises an error when it evaluates the function. ```yaml Type: string @@ -105,10 +106,10 @@ MaximumCount: 1 The `parameters()` function returns the value of the specified parameter. ```yaml -Type: [string, int, bool, object, array] +Type: [string, int, bool, object, array, null] ``` [01]: ../parameter.md -[02]: ../../../cli/config/index.md#--parameters -[03]: ../../../cli/config/index.md#--parameters-file +[02]: ../../../cli/config/index.md#-p---parameters +[03]: ../../../cli/config/index.md#-f---parameters-file diff --git a/docs/reference/schemas/config/functions/parseCidr.md b/docs/reference/schemas/config/functions/parseCidr.md index 20cea2c70..dbc8a9d28 100644 --- a/docs/reference/schemas/config/functions/parseCidr.md +++ b/docs/reference/schemas/config/functions/parseCidr.md @@ -1,6 +1,6 @@ --- description: Reference for the 'parseCidr' DSC configuration document function -ms.date: 11/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: parseCidr --- @@ -88,7 +88,9 @@ resources: - name: Calculate subnet details type: Microsoft.DSC.Debug/Echo properties: - output: "[parseCidr(cidrSubnet(parameters('baseNetwork'), parameters('subnetPrefix'), parameters('subnetIndex')))]" + output: >- + [parseCidr(cidrSubnet(parameters('baseNetwork'), parameters('subnetPrefix'), + parameters('subnetIndex')))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/path.md b/docs/reference/schemas/config/functions/path.md index edc01ad80..b657d3ff4 100644 --- a/docs/reference/schemas/config/functions/path.md +++ b/docs/reference/schemas/config/functions/path.md @@ -1,6 +1,6 @@ --- description: Reference for the 'path' DSC configuration document function -ms.date: 06/04/2025 +ms.date: 09/01/2026 ms.topic: reference title: path --- @@ -20,13 +20,13 @@ path(, , ...) ## Description The `path()` function takes a base path and any number of child items to combine -into a single path, accounting for duplicate `/` characters. +into a single path, accounting for duplicate `/` characters. ## Examples ### Example 1 - Construct with child path -This configuration constructs a simple absolute path of two elements. +This configuration constructs a simple absolute path of two elements. ```yaml # parseChildPath.example.1.dsc.config.yaml @@ -55,7 +55,7 @@ hadErrors: false ### Example 2 - Relative path with multiple elements -This configuration constructs a simple relative path of three elements. +This configuration constructs a simple relative path of three elements. ```yaml # relativePath.example.2.dsc.config.yaml @@ -84,7 +84,7 @@ hadErrors: false ### Example 3 - Relative element in path -This configuration constructs a path with a double dot in that path. +This configuration constructs a path with a double dot in that path. The path is returned as-is and is not resolved to an absolute path. @@ -129,6 +129,7 @@ Type: string Required: true Position: 1 ``` + ### child Defines the child path segments the function appends to the base path. The function expects at @@ -160,11 +161,12 @@ The output path for the same input depends on the operating systems: - The function uses the operating system's defined path separator for appending child path segments to the base path (`\` for Windows and `/` for Linux and macOS). - - For example, `[path('a', 'b', 'c')]` resolves to `a\b\c` on Windows and `a/b/c` on Linux and macOS. + + For example, `[path('a', 'b', 'c')]` resolves to `a\b\c` on Windows and `a/b/c` on Linux and + macOS. - On Windows, specifying a child path segment that begins with a drive letter _replaces_ the constructed path instead of appending to it. - + For example, `[path('./a', 'b', 'C:\', 'd')]` resolves to `C:\d` on Windows and `./a/b/C:\/d` on non-Windows systems. @@ -185,4 +187,4 @@ The function returns an error in the following cases: [01]: ./join.md -[02]: ./uri.md \ No newline at end of file +[02]: ./uri.md diff --git a/docs/reference/schemas/config/functions/range.md b/docs/reference/schemas/config/functions/range.md index 94058cdc5..63bbf4399 100644 --- a/docs/reference/schemas/config/functions/range.md +++ b/docs/reference/schemas/config/functions/range.md @@ -1,10 +1,12 @@ --- description: Reference for the 'range' DSC configuration document function -ms.date: 09/26/2025 +ms.date: 09/01/2026 ms.topic: reference title: range --- +# range + ## Synopsis Creates an array of integers from a starting integer and containing a number of diff --git a/docs/reference/schemas/config/functions/reference.md b/docs/reference/schemas/config/functions/reference.md index 335666281..c986091a0 100644 --- a/docs/reference/schemas/config/functions/reference.md +++ b/docs/reference/schemas/config/functions/reference.md @@ -1,6 +1,6 @@ --- description: Reference for the 'reference' DSC configuration document function -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: reference --- @@ -37,9 +37,10 @@ earlier instances. The instances don't need to be of the same type. ### Example 1 - Referencing a top-level instance -In this example configuration, the `Microsoft.DSC.Debug/Echo` resource instance echoes the `bitness` property of -the `Microsoft/OSInfo` resource. It uses the `reference()` function to retrieve the actual state of -the resource and uses the dot-path notation to access the **bitness** property of that resource. +In this example configuration, the `Microsoft.DSC.Debug/Echo` resource instance echoes the +`bitness` property of the `Microsoft/OSInfo` resource. It uses the `reference()` function to +retrieve the actual state of the resource and uses the dot-path notation to access the +**bitness** property of that resource. ```yaml # reference.example.1.dsc.config.yaml @@ -126,7 +127,8 @@ operation: - [Simple set response][08] You can use dot-notation to access the properties of the referenced instance, as in -[Example 1](#example-1---referencing-a-top-level-instance). +[Example 1](#example-1---referencing-a-top-level-instance). When you access a property this +way, the function returns the value of that property, which can be any JSON type. > [!NOTE] > You can't reuse references to `actualState` for `get` and `test` operations in the `set` @@ -135,7 +137,7 @@ You can use dot-notation to access the properties of the referenced instance, as > want to use a reference for all three operations. ```yaml -Type: [Object, Array] +Type: [array, boolean, number, object, string] ``` diff --git a/docs/reference/schemas/config/functions/resourceId.md b/docs/reference/schemas/config/functions/resourceId.md index 25cb29b2c..18cf4ba2b 100644 --- a/docs/reference/schemas/config/functions/resourceId.md +++ b/docs/reference/schemas/config/functions/resourceId.md @@ -1,6 +1,6 @@ --- description: Reference for the 'resourceId' DSC configuration document function -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: resourceId --- @@ -90,7 +90,7 @@ The value of the [type][03] property of the resource instance to reference. The ```yaml Type: string Required: true -Position: 0 +Position: 1 ``` ### instanceName @@ -100,7 +100,19 @@ The value of the [name][05] property of the resource instance to reference. ```yaml Type: string Required: true -Position: 0 +Position: 2 +``` + +## Output + +The `resourceId()` function returns a string that uniquely identifies the resource instance. The +string has the format `:`. DSC percent-encodes the instance name, +so spaces and other special characters are escaped. For example, +`[resourceId('Microsoft.Windows/Registry', 'Tailspin Key')]` returns +`Microsoft.Windows/Registry:Tailspin%20Key`. + +```yaml +Type: string ``` diff --git a/docs/reference/schemas/config/functions/shallowMerge.md b/docs/reference/schemas/config/functions/shallowMerge.md index f2ad2c0cb..a85b65711 100644 --- a/docs/reference/schemas/config/functions/shallowMerge.md +++ b/docs/reference/schemas/config/functions/shallowMerge.md @@ -1,10 +1,12 @@ --- description: Reference for the 'shallowMerge' DSC configuration document function -ms.date: 11/19/2025 +ms.date: 09/01/2026 ms.topic: reference title: shallowMerge --- +# shallowMerge + ## Synopsis Combines an array of objects into a single object where only the top-level properties are merged. @@ -23,25 +25,25 @@ the value from the last object in the array with that property takes precedence. This is a _shallow merge_, which applies the following rules: -- The first object in the array defines the base value for the merged object. -- The function processes each object in the array in the order they're defined. -- When processing each object, the function iterates over every top-level property defined for that - object and: +- The first object in the array defines the base value for the merged object. +- The function processes each object in the array in the order they're defined. +- When processing each object, the function iterates over every top-level property defined for that + object and: - - If the merged object doesn't already have the property, the function adds that property to the - merged object with the value from the current object. - - If the merged object does have the property, the function _replaces_ the existing value with - the value from the current object, even when the value is an object or array. + - If the merged object doesn't already have the property, the function adds that property to the + merged object with the value from the current object. + - If the merged object does have the property, the function _replaces_ the existing value with + the value from the current object, even when the value is an object or array. This function is useful for: -- Building composite configuration objects from multiple sources. -- Applying configuration overrides where later values take precedence. -- Combining default settings with user-specified customizations. +- Building composite configuration objects from multiple sources. +- Applying configuration overrides where later values take precedence. +- Combining default settings with user-specified customizations. - Merging environment-specific configurations. -The shallow merge behavior differs from a deep merge (like [`union()`][00]) where nested -objects are recursively merged. The `shallowMerge()` function replaces nested structures +The shallow merge behavior differs from a deep merge (like [`union()`][00]) where nested +objects are recursively merged. The `shallowMerge()` function replaces nested structures entirely with the value defined by the last object with that property in the input array. ## Examples @@ -85,7 +87,7 @@ messages: [] hadErrors: false ``` -In this example, the `port` value from the second object (`9000`) replaces the value from the first +In this example, the `port` value from the second object (`9000`) replaces the value from the first object (`8080`), while properties that only exist in one object (`host` and `ssl`) are preserved. ### Example 2 - Apply multiple configuration layers @@ -115,13 +117,13 @@ resources: - name: Echo type: Microsoft.DSC.Debug/Echo properties: - output: >- - [shallowMerge( - createArray( - parameters('defaults'), - parameters('environment'), - parameters('userPrefs') - ) + output: >- + [shallowMerge( + createArray( + parameters('defaults'), + parameters('environment'), + parameters('userPrefs') + ) )] ``` @@ -158,18 +160,18 @@ resources: - name: Echo type: Microsoft.DSC.Debug/Echo properties: - output: >- - [shallowMerge( - createArray( - createObject( - 'database', - createObject('host', 'localhost', 'port', 5432, 'ssl', true()) - ), - createObject( - 'database', - createObject('host', 'prod.db.local') - ) - ) + output: >- + [shallowMerge( + createArray( + createObject( + 'database', + createObject('host', 'localhost', 'port', 5432, 'ssl', true()) + ), + createObject( + 'database', + createObject('host', 'prod.db.local') + ) + ) )] ``` @@ -204,13 +206,13 @@ resources: - name: Echo type: Microsoft.DSC.Debug/Echo properties: - output: >- - [shallowMerge( - createArray( - createObject('name', 'Service1', 'enabled', true()), - createObject(), - createObject('version', '2.0') - ) + output: >- + [shallowMerge( + createArray( + createObject('name', 'Service1', 'enabled', true()), + createObject(), + createObject('version', '2.0') + ) )] ``` @@ -246,12 +248,12 @@ resources: - name: Echo type: Microsoft.DSC.Debug/Echo properties: - output: >- - [shallowMerge( - createArray( - createObject('newUI', false(), 'darkMode', true(), 'beta', false()), - createObject('newUI', true()), createObject('beta', true()) - ) + output: >- + [shallowMerge( + createArray( + createObject('newUI', false(), 'darkMode', true(), 'beta', false()), + createObject('newUI', true()), createObject('beta', true()) + ) )] ``` @@ -344,33 +346,33 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - merged: >- - [shallowMerge( - createArray( - parameters('baseConfig'), - parameters('overrides') - ) - )] - keys: >- - [objectKeys( - shallowMerge( - createArray( - parameters('baseConfig'), - parameters('overrides') - ) - ) - )] - hasRetries: >- - [contains( - objectKeys( - shallowMerge( - createArray( - parameters('baseConfig'), - parameters('overrides') - ) - ) - ), - 'retries' + merged: >- + [shallowMerge( + createArray( + parameters('baseConfig'), + parameters('overrides') + ) + )] + keys: >- + [objectKeys( + shallowMerge( + createArray( + parameters('baseConfig'), + parameters('overrides') + ) + ) + )] + hasRetries: >- + [contains( + objectKeys( + shallowMerge( + createArray( + parameters('baseConfig'), + parameters('overrides') + ) + ) + ), + 'retries' )] ``` @@ -448,8 +450,8 @@ Position: 1 ## Output -Returns a single object containing all properties from the input objects. When the same property -appears in multiple objects, the value from the last object in the array with that property is +Returns a single object containing all properties from the input objects. When the same property +appears in multiple objects, the value from the last object in the array with that property is retained, replacing all prior values for the property. ```yaml @@ -465,13 +467,13 @@ The function will return an error in the following cases: ## Notes - This function performs a _shallow merge_ - the function replaces nested objects, it doesn't merge - them recursively. -- The function replaces the value for properties defined by earlier objects in the input array with - the value from objects later in the array. -- The function ignores empty objects in the input array. -- The function ignores non-object elements in the input array. -- The function returns an empty object when the input is an empty array. -- The function processes objects in array order, so the last object has highest precedence + them recursively. +- The function replaces the value for properties defined by earlier objects in the input array with + the value from objects later in the array. +- The function ignores empty objects in the input array. +- The function ignores non-object elements in the input array. +- The function returns an empty object when the input is an empty array. +- The function processes objects in array order, so the last object has highest precedence - For recursive/deep merging of nested objects, consider using [`union()`][00] instead. ## Related functions diff --git a/docs/reference/schemas/config/functions/skip.md b/docs/reference/schemas/config/functions/skip.md index 7b3faa262..222a58ff9 100644 --- a/docs/reference/schemas/config/functions/skip.md +++ b/docs/reference/schemas/config/functions/skip.md @@ -1,10 +1,12 @@ --- description: Reference for the 'skip' DSC configuration document function -ms.date: 08/29/2025 +ms.date: 09/01/2026 ms.topic: reference title: skip --- +# skip + ## Synopsis Returns an array with all the elements after the specified number in the array, diff --git a/docs/reference/schemas/config/functions/startsWith.md b/docs/reference/schemas/config/functions/startsWith.md index 233bb4d1d..2980ecb6d 100644 --- a/docs/reference/schemas/config/functions/startsWith.md +++ b/docs/reference/schemas/config/functions/startsWith.md @@ -1,6 +1,6 @@ --- description: Reference for the 'startsWith' DSC configuration document function -ms.date: 08/12/2025 +ms.date: 09/01/2026 ms.topic: reference title: startsWith --- @@ -78,7 +78,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - classification: "[if(startsWith(parameters('serviceName'), 'api-'), 'API Service', 'Other Service')]" + classification: >- + [if(startsWith(parameters('serviceName'), 'api-'), 'API Service', + 'Other Service')] ``` ```bash diff --git a/docs/reference/schemas/config/functions/stateChanged.md b/docs/reference/schemas/config/functions/stateChanged.md index ff91a2c6d..d556945c3 100644 --- a/docs/reference/schemas/config/functions/stateChanged.md +++ b/docs/reference/schemas/config/functions/stateChanged.md @@ -1,6 +1,6 @@ --- description: Reference for the 'stateChanged' DSC configuration document function -ms.date: 07/11/2026 +ms.date: 09/01/2026 ms.topic: reference title: stateChanged --- @@ -53,7 +53,9 @@ resources: - name: Report change type: Microsoft.DSC.Debug/Echo properties: - output: "[stateChanged(resourceId('Microsoft.Windows/FeatureOnDemandList', 'Install OpenSSH Client'))]" + output: >- + [stateChanged(resourceId('Microsoft.Windows/FeatureOnDemandList', + 'Install OpenSSH Client'))] dependsOn: - "[resourceId('Microsoft.Windows/FeatureOnDemandList', 'Install OpenSSH Client')]" ``` diff --git a/docs/reference/schemas/config/functions/stdout.md b/docs/reference/schemas/config/functions/stdout.md new file mode 100644 index 000000000..b16fec02a --- /dev/null +++ b/docs/reference/schemas/config/functions/stdout.md @@ -0,0 +1,179 @@ +--- +description: Reference for the 'stdout' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: stdout +--- + +# stdout + +## Synopsis + +Returns the standard output of the command that a DSC extension ran to import a file, for use in +the `output` expression of the extension manifest's `import` method. + +## Syntax + +```Syntax +stdout() +``` + +## Description + +The `stdout()` function returns, as a string, the standard output that DSC captured from the last +command it ran. DSC only provides this value in one situation: when it processes the `output` +expression of an extension's `import` method. + +When you pass a file to DSC with the `--file` option, DSC first checks whether any discovered +extension with the `import` capability lists the file's extension in the `fileExtensions` property +of its `import` method. If one does, DSC runs the command defined by that method's `executable` +and `args` properties and captures the command's standard output. Then: + +- If the `import` method doesn't define the `output` property, DSC uses the captured standard + output as the imported content. +- If the `import` method defines the `output` property, DSC evaluates that property as an + expression. Inside the expression, `stdout()` returns the captured standard output. DSC converts + the value the expression returns to JSON and uses it as the imported content. + +DSC then processes the imported content as the configuration document. + +Use `stdout()` when the command's standard output isn't a configuration document by itself but +contains one or can be converted into one. For example, the expression can parse the output with +[`json()`][00] and use the property access syntax to extract the document from a wrapper object. + +The `output` expression must return an object for the imported content to be a valid +configuration document. If the expression returns a string, DSC converts it to a JSON string +literal, which isn't a valid document. To use the standard output as-is, omit the `output` +property instead of defining it as `[stdout()]`. + +DSC evaluates the `output` expression in a new, empty context. The expression can't access +configuration parameters, variables, or resource references. It can only use `stdout()` and +functions that don't depend on the configuration document. + +Despite the wording of the description in the output of `dsc function list`, DSC doesn't provide +the standard output of resources to configuration documents. Using `stdout()` in a configuration +document always raises an error. + +## Examples + +### Example 1 - Import a wrapped configuration document + +The following extension manifest defines an `import` method for files with the `wrapped` file +extension. The command uses PowerShell to read the file and write its content to standard output. +The `output` expression parses that output with [`json()`][00] and returns the `document` +property, which contains the actual configuration document. + +Save the manifest as `wrapped.dsc.extension.json` in a folder that's included in the `PATH` +environment variable so DSC can discover it. + +```json +{ + "$schema": "https://aka.ms/dsc/schemas/v3/bundled/extension/manifest.json", + "type": "Example.Import/Wrapped", + "version": "0.1.0", + "description": "Imports configuration documents wrapped in a JSON envelope.", + "import": { + "fileExtensions": ["wrapped"], + "executable": "pwsh", + "args": ["-NoProfile", "-Command", "Get-Content", "-Raw", { "fileArg": "-Path" }], + "output": "[json(stdout()).document]" + } +} +``` + +When an entry in `args` is an object with the `fileArg` property, DSC replaces it with the value +of `fileArg` followed by the absolute path to the file being imported. + +The following file wraps a configuration document in an object with `format` and `document` +properties. Save it as `stdout.example.1.dsc.config.wrapped`. + +```json +{ + "format": "wrapped", + "document": { + "$schema": "https://aka.ms/dsc/schemas/v3/bundled/config/document.json", + "resources": [ + { + "name": "Echo", + "type": "Microsoft.DSC.Debug/Echo", + "properties": { + "output": "Imported through stdout()" + } + } + ] + } +} +``` + +```bash +dsc config get --file stdout.example.1.dsc.config.wrapped +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Imported through stdout() +messages: [] +hadErrors: false +``` + +When DSC processes this command, it: + +1. Discovers the `Example.Import/Wrapped` extension and matches the file's `wrapped` extension + against the `fileExtensions` property. +1. Runs `pwsh -NoProfile -Command Get-Content -Raw -Path ` and captures + the standard output. +1. Evaluates `[json(stdout()).document]`, where `stdout()` returns the captured content. +1. Processes the object returned by the expression as the configuration document. + +## Parameters + +The function doesn't accept any arguments. + +## Output + +Returns the standard output that DSC captured from the extension's import command. + +```yaml +Type: string +``` + +## Error conditions + +The function raises an error in the following cases: + +- **No standard output available**: The function is used anywhere other than in the `output` + expression of an extension's `import` method, including in a configuration document. DSC raises + `No standard output is available from the last executed resource`. +- **Arguments passed**: The function is called with one or more arguments. DSC raises + `Function 'stdout' does not accept arguments`. + +If the `output` expression itself raises an error while DSC imports a file, DSC doesn't report +that error. Instead, it tries any other extension with the `import` capability and then reads the +file directly as a configuration document, which usually fails with a parsing error about the +file's content. + +## Notes + +- The only place DSC sets the value that `stdout()` returns is when it processes the `output` + expression of an extension's `import` method. Resources don't expose their standard output to + configuration documents through this function. +- DSC only evaluates the `output` expression when the import command wrote something to standard + output. +- DSC evaluates the `output` expression in a new context without any configuration parameters or + variables. +- The `output` expression should return an object, not a string, so that the imported content is + a valid configuration document. +- For more information about extension manifests, see the + [DSC extension manifest schema reference][01]. + +## Related functions + +- [`json()`][00] - Parses a JSON string and returns the resulting value + + +[00]: ./json.md +[01]: ../../extension/manifest/root.md diff --git a/docs/reference/schemas/config/functions/string.md b/docs/reference/schemas/config/functions/string.md index 23dcd2590..9c92ef73e 100644 --- a/docs/reference/schemas/config/functions/string.md +++ b/docs/reference/schemas/config/functions/string.md @@ -1,6 +1,6 @@ --- description: Reference for the 'string' DSC configuration document function -ms.date: 08/09/2025 +ms.date: 09/01/2026 ms.topic: reference title: string --- @@ -145,13 +145,16 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - deploymentInfo: "[concat('Deployment ', string(parameters('deploymentId')), ' running in ', if(parameters('isProduction'), 'production', 'development'), ' mode')]" - serverMessage: "[concat('Managing ', string(parameters('serverCount')), ' server(s)')]" + deploymentInfo: >- + [concat('Deployment ', string(parameters('deploymentId')), ' running in ', + if(parameters('isProduction'), 'production', 'development'), ' mode')] + serverMessage: >- + [concat('Managing ', string(parameters('serverCount')), ' server(s)')] statusFlag: "[concat('Production: ', string(parameters('isProduction')))]" ``` ```bash -dsc config get --file string.example.4.dsc.config.yaml +dsc config get --file string.example.3.dsc.config.yaml ``` ```yaml @@ -193,11 +196,13 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - logEntry: "[concat('[', string(parameters('timestamp')), '] ERROR ', string(parameters('errorCode')), ': ', string(parameters('metadata')))]" + logEntry: >- + [concat('[', string(parameters('timestamp')), '] ERROR ', + string(parameters('errorCode')), ': ', string(parameters('metadata')))] ``` ```bash -dsc config get --file string.example.5.dsc.config.yaml +dsc config get --file string.example.4.dsc.config.yaml ``` ```yaml @@ -207,7 +212,7 @@ results: result: actualState: output: - logEntry: '[1691596800] ERROR 404: {"level":"error","source":"api"}' + logEntry: '[1691596800] ERROR 404: {"source":"api","level":"error"}' messages: [] hadErrors: false ``` diff --git a/docs/reference/schemas/config/functions/sub.md b/docs/reference/schemas/config/functions/sub.md index c3e57423a..a83bceafb 100644 --- a/docs/reference/schemas/config/functions/sub.md +++ b/docs/reference/schemas/config/functions/sub.md @@ -1,6 +1,6 @@ --- description: Reference for the 'sub' DSC configuration document function -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: sub --- @@ -19,8 +19,8 @@ sub() ## Description -The `sub()` function returns the difference of two integers. It subtracts the second operand from the -first operand. You can nest calls to `sub()` to subtract more than two integers. +The `sub()` function returns the difference of two integers. It subtracts the second operand from +the first operand. You can nest calls to `sub()` to subtract more than two integers. ## Examples diff --git a/docs/reference/schemas/config/functions/systemRoot.md b/docs/reference/schemas/config/functions/systemRoot.md index 9ec5e6809..27173635c 100644 --- a/docs/reference/schemas/config/functions/systemRoot.md +++ b/docs/reference/schemas/config/functions/systemRoot.md @@ -1,6 +1,6 @@ --- description: Reference for the 'systemRoot' DSC configuration document function -ms.date: 06/04/2025 +ms.date: 09/01/2026 ms.topic: reference title: systemRoot --- @@ -84,15 +84,15 @@ hadErrors: false ## Output -The `systemRoot()` function returns the system root of the current host, or the value overriden +The `systemRoot()` function returns the system root of the current host, or the value overridden using the [`--system-root` command line flag][01]. -This is usually `C:\` on Windows system and `/` on Unix systems. +This is usually `C:\` on Windows systems and `/` on Unix systems. ```yaml Type: string ``` -[01]: ../../../cli/config/index.md#--system-root -[02]: ./path.md \ No newline at end of file +[01]: ../../../cli/config/index.md#-r---system-root +[02]: ./path.md diff --git a/docs/reference/schemas/config/functions/take.md b/docs/reference/schemas/config/functions/take.md index ea8e23108..0371f9b10 100644 --- a/docs/reference/schemas/config/functions/take.md +++ b/docs/reference/schemas/config/functions/take.md @@ -1,10 +1,12 @@ --- description: Reference for the 'take' DSC configuration document function -ms.date: 11/01/2025 +ms.date: 09/01/2026 ms.topic: reference title: take --- +# take + ## Synopsis Returns an array with the specified number of elements from the start of an @@ -113,7 +115,8 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - resources: "[createArray('prod-db-east-01', 'dev-api-west-02', 'test-cache-central')]" + resources: >- + [createArray('prod-db-east-01', 'dev-api-west-02', 'test-cache-central')] prodPrefix: "[take('prod-db-east-01', 4)]" devPrefix: "[take('dev-api-west-02', 3)]" testPrefix: "[take('test-cache-central', 4)]" diff --git a/docs/reference/schemas/config/functions/toLower.md b/docs/reference/schemas/config/functions/toLower.md index 2227a129c..2d5674dd1 100644 --- a/docs/reference/schemas/config/functions/toLower.md +++ b/docs/reference/schemas/config/functions/toLower.md @@ -1,6 +1,6 @@ --- description: Reference for the 'toLower' DSC configuration document function -ms.date: 10/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: toLower --- @@ -85,7 +85,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - filePath: "[concat('/etc/', toLower(parameters('fileName')), '.', toLower(parameters('extension')))]" + filePath: >- + [concat('/etc/', toLower(parameters('fileName')), '.', + toLower(parameters('extension')))] ``` ```bash @@ -124,7 +126,8 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - matches: "[equals(toLower(parameters('userInput')), toLower(parameters('expectedValue')))]" + matches: >- + [equals(toLower(parameters('userInput')), toLower(parameters('expectedValue')))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/toUpper.md b/docs/reference/schemas/config/functions/toUpper.md index 48f367171..5565528c0 100644 --- a/docs/reference/schemas/config/functions/toUpper.md +++ b/docs/reference/schemas/config/functions/toUpper.md @@ -1,6 +1,6 @@ --- description: Reference for the 'toUpper' DSC configuration document function -ms.date: 10/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: toUpper --- @@ -85,7 +85,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - configKey: "[concat(toUpper(parameters('environment')), '_', toUpper(parameters('component')), '_CONFIG')]" + configKey: >- + [concat(toUpper(parameters('environment')), '_', + toUpper(parameters('component')), '_CONFIG')] ``` ```bash @@ -124,7 +126,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - result: "[if(parameters('shouldCapitalize'), toUpper(parameters('text')), parameters('text'))]" + result: >- + [if(parameters('shouldCapitalize'), toUpper(parameters('text')), + parameters('text'))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/tryGet.md b/docs/reference/schemas/config/functions/tryGet.md index 1e87f08d2..d42ff1314 100644 --- a/docs/reference/schemas/config/functions/tryGet.md +++ b/docs/reference/schemas/config/functions/tryGet.md @@ -1,10 +1,12 @@ --- description: Reference for the 'tryGet' DSC configuration document function -ms.date: 01/29/2025 +ms.date: 09/01/2026 ms.topic: reference title: tryGet --- +# tryGet + ## Synopsis Safely retrieves a value from an array by index or an object by key without @@ -54,9 +56,14 @@ resources: properties: output: config: "[createObject('enableBeta', true, 'enableDebug', false)]" - betaEnabled: "[coalesce(tryGet(createObject('enableBeta', true, 'enableDebug', false), 'enableBeta'), false)]" - alphaEnabled: "[coalesce(tryGet(createObject('enableBeta', true, 'enableDebug', false), 'enableAlpha'), false)]" - debugEnabled: "[tryGet(createObject('enableBeta', true, 'enableDebug', false), 'enableDebug')]" + betaEnabled: >- + [coalesce(tryGet(createObject('enableBeta', true, 'enableDebug', false), + 'enableBeta'), false)] + alphaEnabled: >- + [coalesce(tryGet(createObject('enableBeta', true, 'enableDebug', false), + 'enableAlpha'), false)] + debugEnabled: >- + [tryGet(createObject('enableBeta', true, 'enableDebug', false), 'enableDebug')] ``` ```bash @@ -112,7 +119,8 @@ resources: productionEnv: "[tryGet(parameters('environments'), 'production')]" stagingEnv: "[tryGet(parameters('environments'), 'staging')]" developmentEnv: "[tryGet(parameters('environments'), 'development')]" - prodReplicas: "[tryGet(tryGet(parameters('environments'), 'production'), 'replicas')]" + prodReplicas: >- + [tryGet(tryGet(parameters('environments'), 'production'), 'replicas')] prodRegion: "[tryGet(tryGet(parameters('environments'), 'production'), 'region')]" stagingRegion: "[tryGet(tryGet(parameters('environments'), 'staging'), 'region')]" ``` @@ -212,10 +220,15 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - successResponse: "[createObject('status', 200, 'data', createObject('id', 123, 'name', 'example'))]" + successResponse: >- + [createObject('status', 200, 'data', createObject('id', 123, 'name', 'example'))] errorResponse: "[createObject('status', 404, 'error', 'Not Found')]" - successData: "[tryGet(createObject('status', 200, 'data', createObject('id', 123, 'name', 'example')), 'data')]" - successError: "[tryGet(createObject('status', 200, 'data', createObject('id', 123, 'name', 'example')), 'error')]" + successData: >- + [tryGet(createObject('status', 200, 'data', + createObject('id', 123, 'name', 'example')), 'data')] + successError: >- + [tryGet(createObject('status', 200, 'data', + createObject('id', 123, 'name', 'example')), 'error')] errorData: "[tryGet(createObject('status', 404, 'error', 'Not Found'), 'data')]" errorMessage: "[tryGet(createObject('status', 404, 'error', 'Not Found'), 'error')]" ``` diff --git a/docs/reference/schemas/config/functions/tryIndexFromEnd.md b/docs/reference/schemas/config/functions/tryIndexFromEnd.md index 58aab3880..509bacaa0 100644 --- a/docs/reference/schemas/config/functions/tryIndexFromEnd.md +++ b/docs/reference/schemas/config/functions/tryIndexFromEnd.md @@ -1,10 +1,12 @@ --- description: Reference for the 'tryIndexFromEnd' DSC configuration document function -ms.date: 01/29/2025 +ms.date: 09/01/2026 ms.topic: reference title: tryIndexFromEnd --- +# tryIndexFromEnd + ## Synopsis Safely retrieves a value from an array by counting backward from the end without @@ -54,8 +56,10 @@ resources: properties: output: currentDeployment: "[last(createArray('v1.0.0', 'v1.1.0', 'v1.2.0'))]" - previousDeployment: "[tryIndexFromEnd(createArray('v1.0.0', 'v1.1.0', 'v1.2.0'), 2)]" - fallbackDeployment: "[tryIndexFromEnd(createArray('v1.0.0', 'v1.1.0', 'v1.2.0'), 10)]" + previousDeployment: >- + [tryIndexFromEnd(createArray('v1.0.0', 'v1.1.0', 'v1.2.0'), 2)] + fallbackDeployment: >- + [tryIndexFromEnd(createArray('v1.0.0', 'v1.1.0', 'v1.2.0'), 10)] ``` ```bash @@ -213,8 +217,11 @@ resources: output: primaryRegion: "[createArray('us-east-1', 'us-west-2', 'eu-west-1')]" secondaryRegion: "[createArray('us-west-1')]" - preferredPrimary: "[coalesce(tryIndexFromEnd(createArray('us-east-1', 'us-west-2', 'eu-west-1'), 2), 'us-east-1')]" - preferredSecondary: "[coalesce(tryIndexFromEnd(createArray('us-west-1'), 2), 'us-west-1')]" + preferredPrimary: >- + [coalesce(tryIndexFromEnd(createArray('us-east-1', 'us-west-2', 'eu-west-1'), 2), + 'us-east-1')] + preferredSecondary: >- + [coalesce(tryIndexFromEnd(createArray('us-west-1'), 2), 'us-west-1')] ``` ```bash diff --git a/docs/reference/schemas/config/functions/tryWhich.md b/docs/reference/schemas/config/functions/tryWhich.md index 6fba50259..6ea9e8fc0 100644 --- a/docs/reference/schemas/config/functions/tryWhich.md +++ b/docs/reference/schemas/config/functions/tryWhich.md @@ -1,10 +1,12 @@ --- description: Reference for the 'tryWhich' DSC configuration document function -ms.date: 11/19/2025 +ms.date: 09/01/2026 ms.topic: reference title: tryWhich --- +# tryWhich + ## Synopsis Looks for an executable in the `PATH` environment variable and returns the full path to the first @@ -41,8 +43,8 @@ gracefully returns `null`, making it ideal for conditional logic with [`if()`][0 ### Example 1 - Check if tool exists before using it -The following example uses `tryWhich()` with [`if()`][00] to conditionally set a property -based on whether the `git` command is available. +The following example uses `tryWhich()` with [`not()`][06] and [`equals()`][03] to set a +property based on whether the `git` command is available. ```yaml # tryWhich.example.1.dsc.config.yaml @@ -53,12 +55,7 @@ resources: properties: output: gitPath: "[tryWhich('git')]" - hasGit: >- - [if( - equals(tryWhich('git'), null()), - false(), - true() - )] + hasGit: "[not(equals(tryWhich('git'), null()))]" ``` ```bash @@ -72,14 +69,14 @@ results: result: actualState: output: - gitPath: /usr/bin/git + gitPath: C:\Program Files\Git\cmd\git.exe hasGit: true messages: [] hadErrors: false ``` -If `git` wasn't discoverable in the `PATH` environmental variable, `gitPath` would be `null` and `hasGit` -would be `false`. +If `git` wasn't discoverable in the `PATH` environmental variable, `gitPath` would be `null` and +`hasGit` would be `false`. ### Example 2 - Provide fallback paths with coalesce diff --git a/docs/reference/schemas/config/functions/union.md b/docs/reference/schemas/config/functions/union.md index bd13c3269..99ba200ff 100644 --- a/docs/reference/schemas/config/functions/union.md +++ b/docs/reference/schemas/config/functions/union.md @@ -1,6 +1,6 @@ --- description: Reference for the 'union' DSC configuration document function -ms.date: 08/08/2025 +ms.date: 09/01/2026 ms.topic: reference title: union --- @@ -62,7 +62,9 @@ resources: properties: output: allServers: "[union(parameters('serverGroup1'), parameters('serverGroup2'))]" - threeGroups: "[union(parameters('serverGroup1'), parameters('serverGroup2'), parameters('serverGroup3'))]" + threeGroups: >- + [union(parameters('serverGroup1'), parameters('serverGroup2'), + parameters('serverGroup3'))] ``` ```bash @@ -122,7 +124,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - finalConfig: "[union(parameters('defaultConfig'), parameters('userConfig'), parameters('envConfig'))]" + finalConfig: >- + [union(parameters('defaultConfig'), parameters('userConfig'), + parameters('envConfig'))] ``` ```bash @@ -229,7 +233,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - logEntry: "[string(union(parameters('baseLogData'), parameters('requestData'), parameters('responseData')))]" + logEntry: >- + [string(union(parameters('baseLogData'), parameters('requestData'), + parameters('responseData')))] logArray: "[union(createArray('timestamp'), createArray('level', 'requestId'))]" ``` diff --git a/docs/reference/schemas/config/functions/uniqueString.md b/docs/reference/schemas/config/functions/uniqueString.md index c1340a0fd..18b9fe79e 100644 --- a/docs/reference/schemas/config/functions/uniqueString.md +++ b/docs/reference/schemas/config/functions/uniqueString.md @@ -1,6 +1,6 @@ --- description: Reference for the 'uniqueString' DSC configuration document function -ms.date: 08/12/2025 +ms.date: 09/01/2026 ms.topic: reference title: uniqueString --- @@ -57,7 +57,8 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - name: "[uniqueString(parameters('env'), parameters('service'), parameters('region'))]" + name: >- + [uniqueString(parameters('env'), parameters('service'), parameters('region'))] ``` ```bash @@ -135,7 +136,8 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - resourceId: "[concat('res-', uniqueString(parameters('project'), parameters('zone')))]" + resourceId: >- + [concat('res-', uniqueString(parameters('project'), parameters('zone')))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/uri.md b/docs/reference/schemas/config/functions/uri.md index 174e70723..58f067af6 100644 --- a/docs/reference/schemas/config/functions/uri.md +++ b/docs/reference/schemas/config/functions/uri.md @@ -1,6 +1,6 @@ --- description: Reference for the 'uri' DSC configuration document function -ms.date: 01/10/2025 +ms.date: 09/01/2026 ms.topic: reference title: uri --- @@ -155,7 +155,9 @@ resources: properties: output: oldEndpoint: "[concat('https://api.example.com/', parameters('currentVersion'))]" - newEndpoint: "[uri(concat('https://api.example.com/', parameters('currentVersion')), parameters('newVersion'))]" + newEndpoint: >- + [uri(concat('https://api.example.com/', parameters('currentVersion')), + parameters('newVersion'))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/uriComponent.md b/docs/reference/schemas/config/functions/uriComponent.md index bcf0325d5..3617ce52b 100644 --- a/docs/reference/schemas/config/functions/uriComponent.md +++ b/docs/reference/schemas/config/functions/uriComponent.md @@ -1,6 +1,6 @@ --- description: Reference for the 'uriComponent' DSC configuration document function -ms.date: 01/10/2025 +ms.date: 09/01/2026 ms.topic: reference title: uriComponent --- @@ -51,7 +51,9 @@ resources: output: original: "[parameters('searchTerm')]" encoded: "[uriComponent(parameters('searchTerm'))]" - fullUrl: "[concat('https://example.com/search?q=', uriComponent(parameters('searchTerm')))]" + fullUrl: >- + [concat('https://example.com/search?q=', + uriComponent(parameters('searchTerm')))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/uriComponentToString.md b/docs/reference/schemas/config/functions/uriComponentToString.md index 84f425d65..d06a22972 100644 --- a/docs/reference/schemas/config/functions/uriComponentToString.md +++ b/docs/reference/schemas/config/functions/uriComponentToString.md @@ -1,8 +1,8 @@ --- description: Reference for the 'uriComponentToString' DSC configuration document function -ms.date: 10/10/2025 -ms.topic: reference -title: uriComponentToString function +ms.date: 09/01/2026 +ms.topic: reference +title: uriComponentToString --- # uriComponentToString @@ -13,7 +13,7 @@ Returns a decoded string from a URI-encoded value. ## Syntax -```yaml +```Syntax uriComponentToString() ``` @@ -33,7 +33,7 @@ such as query parameters, path segments, or other URI parts. This example decodes a URI-encoded query parameter value back to its original string. ```yaml -# example1.dsc.yaml +# uriComponentToString.example.1.dsc.config.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Echo decoded value @@ -43,7 +43,7 @@ resources: ``` ```bash -dsc config get --document example1.dsc.yaml config get +dsc config get --file uriComponentToString.example.1.dsc.config.yaml ``` ```yaml @@ -60,7 +60,7 @@ results: This example decodes a URI-encoded email address with special characters. ```yaml -# example2.dsc.yaml +# uriComponentToString.example.2.dsc.config.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Echo decoded email @@ -70,7 +70,7 @@ resources: ``` ```bash -dsc config get --document example2.dsc.yaml config get +dsc config get --file uriComponentToString.example.2.dsc.config.yaml ``` ```yaml @@ -87,17 +87,18 @@ results: This example decodes a completely URI-encoded URL back to its readable form. ```yaml -# example3.dsc.yaml +# uriComponentToString.example.3.dsc.config.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Echo decoded URL type: Microsoft.DSC.Debug/Echo properties: - output: "[uriComponentToString('https%3A%2F%2Fapi.example.com%2Fusers%3Fstatus%3Dactive')]" + output: >- + [uriComponentToString('https%3A%2F%2Fapi.example.com%2Fusers%3Fstatus%3Dactive')] ``` ```bash -dsc config get --document example3.dsc.yaml config get +dsc config get --file uriComponentToString.example.3.dsc.config.yaml ``` ```yaml @@ -115,7 +116,7 @@ This example demonstrates encoding a string with [`uriComponent()`][01] and then back with `uriComponentToString()`, showing that they are inverse operations. ```yaml -# example4.dsc.yaml +# uriComponentToString.example.4.dsc.config.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Echo round-trip result @@ -125,7 +126,7 @@ resources: ``` ```bash -dsc config get --document example4.dsc.yaml config get +dsc config get --file uriComponentToString.example.4.dsc.config.yaml ``` ```yaml @@ -142,7 +143,7 @@ results: This example decodes a URI-encoded string containing UTF-8 encoded Unicode characters. ```yaml -# example5.dsc.yaml +# uriComponentToString.example.5.dsc.config.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Echo decoded Unicode @@ -152,7 +153,7 @@ resources: ``` ```bash -dsc config get --document example5.dsc.yaml config get +dsc config get --file uriComponentToString.example.5.dsc.config.yaml ``` ```yaml diff --git a/lib/dsc-lib/src/parser/functions.rs b/lib/dsc-lib/src/parser/functions.rs index 6a507a582..68c68c74b 100644 --- a/lib/dsc-lib/src/parser/functions.rs +++ b/lib/dsc-lib/src/parser/functions.rs @@ -43,7 +43,7 @@ pub enum FunctionArg { /// /// Lambdas are created using the `lambda()` function syntax: /// ```text -/// "[lambda(['item', 'index'], mul(variables('item'), 2))]" +/// "[lambda('item', 'index', mul(lambdaVariables('item'), 2))]" /// ``` /// /// The lambda is stored in the context and referenced by UUID: @@ -53,7 +53,7 @@ pub enum FunctionArg { /// /// When used with `map()`, the lambda is invoked for each array element with bound parameters: /// ```text -/// "[map(createArray(1, 2, 3), lambda(['item'], mul(variables('item'), 2)))]" +/// "[map(createArray(1, 2, 3), lambda('item', mul(lambdaVariables('item'), 2)))]" /// ``` /// /// # Lifetime