diff --git a/docs/reference/schemas/config/functions/contains.md b/docs/reference/schemas/config/functions/contains.md new file mode 100644 index 000000000..76fc4db1a --- /dev/null +++ b/docs/reference/schemas/config/functions/contains.md @@ -0,0 +1,199 @@ +--- +description: Reference for the 'contains' DSC configuration document function +ms.date: 08/08/2025 +ms.topic: reference +title: contains +--- + +# contains + +## Synopsis + +Checks whether a collection contains a specific value or whether a string +contains a substring. + +## Syntax + +```Syntax +contains(, ) +``` + +## Description + +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. + +The function accepts string and number values for the search parameter when +used with arrays, objects, or strings. + +## Examples + +### Example 1 - Check array for values + +The following example shows how to check if an array contains specific values. + +```yaml +# contains.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + myArray: + type: array + defaultValue: + - apple + - banana + - 42 + - true +resources: +- name: Check array contents + type: Microsoft.DSC.Debug/Echo + properties: + output: + hasApple: "[contains(parameters('myArray'), 'apple')]" + hasOrange: "[contains(parameters('myArray'), 'orange')]" + hasNumber42: "[contains(parameters('myArray'), 42)]" + hasNumber99: "[contains(parameters('myArray'), 99)]" +``` + +```bash +dsc config get --file contains.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Check array contents + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + hasApple: true + hasOrange: false + hasNumber42: true + hasNumber99: false +messages: [] +hadErrors: false +``` + +### Example 2 - Check object for keys and values + +The following example shows how to check if an object contains specific keys +or values. + +```yaml +# contains.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + myObject: + type: object + defaultValue: + name: John + age: 30 + city: Seattle +resources: +- name: Check object contents + 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)]" +``` + +```bash +dsc config get --file contains.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Check object contents + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + hasNameKey: true + hasEmailKey: false + hasSeattleValue: true + hasAge30Value: true +messages: [] +hadErrors: false +``` + +### Example 3 - Check string for substrings + +The following example shows how to check if a string contains specific +substrings. + +```yaml +# contains.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + myString: + type: string + defaultValue: "Hello DSC 123" +resources: +- name: Check string contents + type: Microsoft.DSC.Debug/Echo + properties: + output: + hasHello: "[contains(parameters('myString'), 'Hello')]" + hasDSC: "[contains(parameters('myString'), 'DSC')]" + hasNumber: "[contains(parameters('myString'), '123')]" + hasXYZ: "[contains(parameters('myString'), 'XYZ')]" +``` + +```bash +dsc config get --file contains.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Check string contents + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + hasHello: true + hasDSC: true + hasNumber: true + hasXYZ: false +messages: [] +hadErrors: false +``` + +## Parameters + +### collection + +The collection to search in (array, object, or string). + +```yaml +Type: [array, object, string] +Required: true +``` + +### value + +The value to search for. Must be a string or number. + +```yaml +Type: [string, number] +Required: true +``` + +The `contains()` function expects exactly two input values. The first +parameter is the collection to search, and the second is the value to find. +Complex objects and arrays cannot be used as search values. + +## Output + +The `contains()` function returns `true` if the collection contains the +specified value and `false` otherwise. + +```yaml +Type: bool +``` + + diff --git a/docs/reference/schemas/config/functions/empty.md b/docs/reference/schemas/config/functions/empty.md new file mode 100644 index 000000000..90fc2a200 --- /dev/null +++ b/docs/reference/schemas/config/functions/empty.md @@ -0,0 +1,215 @@ +--- +description: Reference for the 'empty' DSC configuration document function +ms.date: 08/08/2025 +ms.topic: reference +title: empty +--- + +# empty + +## Synopsis + +Checks whether a value is empty. + +## Syntax + +```Syntax +empty() +``` + +## Description + +The `empty()` function checks whether a value is empty, returning `true` if +it is and `false` otherwise. For arrays and objects, it returns `true` if +they contain no elements or properties. For strings, it returns `true` if +the string is empty (zero length). + +## Examples + +### Example 1 - Check empty arrays + +The following example shows how to check if arrays are empty. + +```yaml +# empty.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + populatedArray: + type: array + defaultValue: + - item1 + - item2 + - item3 + emptyArray: + type: array + defaultValue: [] +resources: +- name: Check array emptiness + type: Microsoft.DSC.Debug/Echo + properties: + output: + populatedEmpty: "[empty(parameters('populatedArray'))]" + emptyArrayEmpty: "[empty(parameters('emptyArray'))]" +``` + +```bash +dsc config get --file empty.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Check array emptiness + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + populatedEmpty: false + emptyArrayEmpty: true +messages: [] +hadErrors: false +``` + +### Example 2 - Check empty objects + +The following example shows how to check if objects are empty. + +```yaml +# empty.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + populatedObject: + type: object + defaultValue: + name: John + age: 30 + emptyObject: + type: object + defaultValue: {} +resources: +- name: Check object emptiness + type: Microsoft.DSC.Debug/Echo + properties: + output: + populatedEmpty: "[empty(parameters('populatedObject'))]" + emptyObjectEmpty: "[empty(parameters('emptyObject'))]" +``` + +```bash +dsc config get --file empty.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Check object emptiness + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + populatedEmpty: false + emptyObjectEmpty: true +messages: [] +hadErrors: false +``` + +### Example 3 - Check empty strings + +The following example shows how to check if strings are empty. + +```yaml +# empty.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + populatedString: + type: string + defaultValue: "Hello World" + emptyString: + type: string + defaultValue: "" +resources: +- name: Check string emptiness + type: Microsoft.DSC.Debug/Echo + properties: + output: + populatedEmpty: "[empty(parameters('populatedString'))]" + emptyStringEmpty: "[empty(parameters('emptyString'))]" + literalEmpty: "[empty('')]" +``` + +```bash +dsc config get --file empty.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Check string emptiness + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + populatedEmpty: false + emptyStringEmpty: true + literalEmpty: true +messages: [] +hadErrors: false +``` + +### Example 4 - Conditional resource deployment + +The following example shows a practical use case for checking if a +configuration array is empty before deploying resources. + +```yaml +# empty.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + serverList: + type: array + defaultValue: [] +resources: +- name: Check if servers configured + type: Microsoft.DSC.Debug/Echo + properties: + output: + message: "[if(empty(parameters('serverList')), 'No servers to configure', concat('Configuring ', string(length(parameters('serverList'))), ' servers'))]" +``` + +```bash +dsc config get --file empty.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Check if servers configured + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + message: "No servers to configure" +messages: [] +hadErrors: false +``` + +## Parameters + +### value + +The value to check for emptiness. + +```yaml +Type: [array, object, string] +Required: true +``` + +The `empty()` function expects exactly one input value of type array, object, +or string. + +## Output + +The `empty()` function returns `true` if the value is empty and `false` +otherwise. + +```yaml +Type: bool +``` + + diff --git a/docs/reference/schemas/config/functions/length.md b/docs/reference/schemas/config/functions/length.md new file mode 100644 index 000000000..fee7f77c2 --- /dev/null +++ b/docs/reference/schemas/config/functions/length.md @@ -0,0 +1,193 @@ +--- +description: Reference for the 'length' DSC configuration document function +ms.date: 08/08/2025 +ms.topic: reference +title: length +--- + +# length + +## Synopsis + +Returns the number of elements in an array, properties in an object, or +characters in a string. + +## Syntax + +```Syntax +length() +``` + +## Description + +The `length()` function returns the number of elements in a collection or +characters in a string. For arrays, it returns the count of elements. For +objects, it returns the count of properties. For strings, it returns the +count of characters. + +## Examples + +### Example 1 - Get array length + +The following example shows how to get the length of arrays. + +```yaml +# length.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + smallArray: + type: array + defaultValue: + - dsc + - v3 + largeArray: + type: array + defaultValue: + - red + - green + - blue + - yellow + - purple + emptyArray: + type: array + defaultValue: [] +resources: +- name: Check array lengths + type: Microsoft.DSC.Debug/Echo + properties: + output: + smallLength: "[length(parameters('smallArray'))]" + largeLength: "[length(parameters('largeArray'))]" + emptyLength: "[length(parameters('emptyArray'))]" +``` + +```bash +dsc config get --file length.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Check array lengths + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + smallLength: 2 + largeLength: 5 + emptyLength: 0 +messages: [] +hadErrors: false +``` + +### Example 2 - Get object property count + +The following example shows how to get the number of properties in objects. + +```yaml +# length.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + userProfile: + type: object + defaultValue: + firstName: John + lastName: Doe + email: john.doe@example.com + age: 30 + emptyConfig: + type: object + defaultValue: {} +resources: +- name: Check object property counts + type: Microsoft.DSC.Debug/Echo + properties: + output: + profileProperties: "[length(parameters('userProfile'))]" + emptyProperties: "[length(parameters('emptyConfig'))]" +``` + +```bash +dsc config get --file length.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Check object property counts + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + profileProperties: 4 + emptyProperties: 0 +messages: [] +hadErrors: false +``` + +### Example 3 - Get string character count + +The following example shows how to get the length of strings. + +```yaml +# length.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + message: + type: string + defaultValue: "Hello DSC!" + longText: + type: string + defaultValue: "This is a longer string with more characters to demonstrate length calculation." +resources: +- name: Check string lengths + type: Microsoft.DSC.Debug/Echo + properties: + output: + messageLength: "[length(parameters('message'))]" + longTextLength: "[length(parameters('longText'))]" + emptyStringLength: "[length('')]" + literalLength: "[length('DSC')]" +``` + +```bash +dsc config get --file length.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Check string lengths + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + messageLength: 10 + longTextLength: 78 + emptyStringLength: 0 + literalLength: 3 +messages: [] +hadErrors: false +``` + +## Parameters + +### value + +The value to get the length of. + +```yaml +Type: [array, object, string] +Required: true +``` + +The `length()` function expects exactly one input value of type array, object, +or string. + +## Output + +The `length()` function returns an integer representing the count of elements, +properties, or characters. + +```yaml +Type: number +``` + + diff --git a/docs/reference/schemas/config/functions/union.md b/docs/reference/schemas/config/functions/union.md new file mode 100644 index 000000000..bd13c3269 --- /dev/null +++ b/docs/reference/schemas/config/functions/union.md @@ -0,0 +1,314 @@ +--- +description: Reference for the 'union' DSC configuration document function +ms.date: 08/08/2025 +ms.topic: reference +title: union +--- + +# union + +## Synopsis + +Combines two or more arrays or objects, returning a single collection with +unique elements or merged properties. + +## Syntax + +```Syntax +union(, , [collection3], ...) +``` + +## Description + +The `union()` function combines multiple collections into a single collection. +For arrays, it returns a new array containing all unique elements from the +input arrays, preserving order and removing duplicates. For objects, it +merges properties from all input objects, with later objects overriding +properties from earlier ones when keys conflict. + +All input parameters must be of the same type (all arrays or all objects). +Mixing arrays and objects will result in an error. + +## Examples + +### Example 1 - Union of arrays + +The following example shows how to combine multiple arrays into one. + +```yaml +# union.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + serverGroup1: + type: array + defaultValue: + - web01 + - web02 + - db01 + serverGroup2: + type: array + defaultValue: + - web02 + - web03 + - cache01 + serverGroup3: + type: array + defaultValue: + - db01 + - backup01 +resources: +- name: Combine server groups + type: Microsoft.DSC.Debug/Echo + properties: + output: + allServers: "[union(parameters('serverGroup1'), parameters('serverGroup2'))]" + threeGroups: "[union(parameters('serverGroup1'), parameters('serverGroup2'), parameters('serverGroup3'))]" +``` + +```bash +dsc config get --file union.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Combine server groups + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + allServers: + - web01 + - web02 + - db01 + - web03 + - cache01 + threeGroups: + - web01 + - web02 + - db01 + - web03 + - cache01 + - backup01 +messages: [] +hadErrors: false +``` + +### Example 2 - Union of objects + +The following example shows how to merge multiple objects. + +```yaml +# union.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + defaultConfig: + type: object + defaultValue: + timeout: 30 + retries: 3 + debug: false + userConfig: + type: object + defaultValue: + timeout: 60 + logLevel: info + envConfig: + type: object + defaultValue: + debug: true + environment: production +resources: +- name: Merge configurations + type: Microsoft.DSC.Debug/Echo + properties: + output: + finalConfig: "[union(parameters('defaultConfig'), parameters('userConfig'), parameters('envConfig'))]" +``` + +```bash +dsc config get --file union.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Merge configurations + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + finalConfig: + timeout: 60 + retries: 3 + debug: true + logLevel: info + environment: production +messages: [] +hadErrors: false +``` + +### Example 3 - Union with duplicate arrays + +The following example shows how union handles duplicate values in arrays. + +```yaml +# union.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + permissions1: + type: array + defaultValue: + - read + - write + - execute + permissions2: + type: array + defaultValue: + - read + - admin + - delete +resources: +- name: Combine permissions + type: Microsoft.DSC.Debug/Echo + properties: + output: + uniquePermissions: "[union(parameters('permissions1'), parameters('permissions2'))]" + selfUnion: "[union(parameters('permissions1'), parameters('permissions1'))]" +``` + +```bash +dsc config get --file union.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Combine permissions + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + uniquePermissions: + - read + - write + - execute + - admin + - delete + selfUnion: + - read + - write + - execute +messages: [] +hadErrors: false +``` + +### Example 5 - Union with string conversion for logging + +The following example shows how to use union with string conversion for +building comprehensive log messages. + +```yaml +# union.example.5.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + baseLogData: + type: object + defaultValue: + timestamp: 1691596800 + level: "INFO" + requestData: + type: object + defaultValue: + requestId: 12345 + method: "GET" + responseData: + type: object + defaultValue: + statusCode: 200 + duration: 150 +resources: +- name: Build comprehensive log entry + type: Microsoft.DSC.Debug/Echo + properties: + output: + logEntry: "[string(union(parameters('baseLogData'), parameters('requestData'), parameters('responseData')))]" + logArray: "[union(createArray('timestamp'), createArray('level', 'requestId'))]" +``` + +```bash +dsc config get --file union.example.5.dsc.config.yaml +``` + +```yaml +results: +- name: Build comprehensive log entry + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + logEntry: '{"timestamp":1691596800,"level":"INFO","requestId":12345,"method":"GET","statusCode":200,"duration":150}' + logArray: + - timestamp + - level + - requestId +messages: [] +hadErrors: false +``` + +## Parameters + +### collection1 + +The first collection to union. + +```yaml +Type: [array, object] +Required: true +``` + +### collection2 + +The second collection to union. Must be the same type as collection1. + +```yaml +Type: [array, object] +Required: true +``` + +### Additional collections + +Additional collections to union (optional). All must be the same type as +collection1. + +```yaml +Type: [array, object] +Required: false +``` + +The `union()` function requires at least two input values and accepts +additional values. All input values must be of the same type (all arrays or +all objects). + +For arrays, the function preserves the order of elements and removes +duplicates. For objects, properties from later objects override properties +from earlier objects when there are key conflicts. + +## Output + +The `union()` function returns a single collection of the same type as the +input collections. + +```yaml +Type: [array, object] +``` + +## Related functions + +- [`createArray()`][00] - Creates arrays that can be combined with union +- [`createObject()`][01] - Creates objects that can be merged with union +- [`string()`][02] - Converts objects or arrays to JSON strings +- [`concat()`][03] - Concatenates arrays (alternative to union for arrays) + + +[00]: ./createArray.md +[01]: ./createObject.md +[02]: ./string.md +[03]: ./concat.md