diff --git a/docs/reference/schemas/config/functions/array.md b/docs/reference/schemas/config/functions/array.md new file mode 100644 index 00000000..08a3686c --- /dev/null +++ b/docs/reference/schemas/config/functions/array.md @@ -0,0 +1,190 @@ +--- +description: Reference for the 'array' DSC configuration document function +ms.date: 08/12/2025 +ms.topic: reference +title: array +--- + +# array + +## Synopsis + +Creates an array from the given elements (strings, numbers, arrays, or objects). + +## Syntax + +```Syntax +array(, , ...) +``` + +## Description + +The `array()` function creates an array from the provided arguments, allowing +mixed data types within the same array. Unlike `createArray()` which requires +all elements to be the same type, `array()` accepts any combination of strings, +numbers, arrays, and objects as arguments. + +This function is useful when you need to combine different types of data into a +single collection, such as mixing configuration values, computed results, and +structured metadata in deployment scenarios. + +## Examples + +### Example 1 - Build a deployment plan + +This example demonstrates combining different data types to create a comprehensive +deployment configuration. The array contains an existing server list, a numeric +batch size, and a configuration object with deployment strategy details. + +```yaml +# array.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + webServers: + type: array + defaultValue: + - web01 + - web02 + batchSize: + type: int + defaultValue: 2 +resources: +- name: Deployment Plan + type: Microsoft.DSC.Debug/Echo + properties: + output: "[array(parameters('webServers'), parameters('batchSize'), createObject('strategy', 'blue-green'))]" +``` + +```bash +dsc config get --file array.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Deployment Plan + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - - web01 + - web02 + - 2 + - strategy: blue-green +messages: [] +hadErrors: false +``` + +### Example 2 - Compose mixed telemetry payload parts + +This example shows how to construct a telemetry payload by combining a string +identifier, structured metadata object, and numeric status code into a single +array for logging or monitoring systems. + +```yaml +# array.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + correlationId: + type: string + defaultValue: ABC123 +resources: +- name: Telemetry Payload + type: Microsoft.DSC.Debug/Echo + properties: + output: + payload: "[array(parameters('correlationId'), createObject('severity', 'info'), 200)]" +``` + +```bash +dsc config get --file array.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Telemetry Payload + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + payload: + - ABC123 + - severity: info + - 200 +messages: [] +hadErrors: false +``` + +### Example 3 - Combine generated and literal collections + +This example demonstrates nesting arrays and objects within a parent array, +showing how `array()` can combine results from other DSC functions like +`createArray()` and `createObject()` with literal values. + +```yaml +# array.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Combined Collections + type: Microsoft.DSC.Debug/Echo + properties: + output: + combined: "[array(createArray('a','b'), array(1,2), createObject('k','v'))]" +``` + +```bash +dsc config get --file array.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Combined Collections + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + combined: + - - a + - b + - - 1 + - 2 + - k: v +messages: [] +hadErrors: false +``` + +## Parameters + +### element1, element2, ... + +The elements to include in the array. + +```yaml +Type: string, number, array, or object +Required: false +Multiplicity: 0 or more +``` + +Each element provided as an argument will be added to the resulting array in the +order specified. All elements must be one of the four accepted types: string, +number (integer), array, or object. Boolean and null values are not supported. + +## Output + +Returns a new array containing the provided elements in order. + +```yaml +Type: array +``` + +## Related functions + +- [`createArray()`][00] - Creates a homogeneous array (all elements same type) +- [`createObject()`][01] - Builds an object from key/value pairs +- [`first()`][02] - Gets the first element from an array +- [`indexOf()`][03] - Finds the index of an item in an array + + +[00]: ./createArray.md +[01]: ./createObject.md +[02]: ./first.md +[03]: ./indexOf.md diff --git a/docs/reference/schemas/config/functions/first.md b/docs/reference/schemas/config/functions/first.md new file mode 100644 index 00000000..84b2d982 --- /dev/null +++ b/docs/reference/schemas/config/functions/first.md @@ -0,0 +1,176 @@ +--- +description: Reference for the 'first' DSC configuration document function +ms.date: 08/12/2025 +ms.topic: reference +title: first +--- + +# first + +## Synopsis + +Returns the first element of an array or the first character of a string. + +## Syntax + +```Syntax +first() +``` + +## Description + +The `first()` function extracts the first element from an array or the first +character from a string. When used with arrays, it returns the actual first +element preserving its original data type (string, number, array, or object). +When used with strings, it returns a new single-character string containing +the first Unicode character. + +This function is particularly useful for accessing the primary or default item +from a collection, or extracting prefixes from identifiers and codes. The +function will return an error if the input array or string is empty. + +## Examples + +### Example 1 - Get the first server hostname + +This example shows how to extract the primary server from a list of servers, +which could be useful for identifying the lead server in a cluster or getting +the default target for deployment operations. + +```yaml +# first.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + servers: + type: array + defaultValue: + - web01 + - web02 +resources: +- name: First Server + type: Microsoft.DSC.Debug/Echo + properties: + output: + firstServer: "[first(parameters('servers'))]" +``` + +```bash +dsc config get --file first.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: First Server + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + firstServer: web01 +messages: [] +hadErrors: false +``` + +### Example 2 - Extract leading character for a prefix + +This example demonstrates extracting the first character from an environment +code to create abbreviated prefixes for resource naming or tagging schemes. + +```yaml +# first.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + environmentCode: + type: string + defaultValue: Prod +resources: +- name: Prefix Builder + type: Microsoft.DSC.Debug/Echo + properties: + output: + prefix: "[first(parameters('environmentCode'))]" +``` + +```bash +dsc config get --file first.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Prefix Builder + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + prefix: P +messages: [] +hadErrors: false +``` + +### Example 3 - Chain with array construction + +This example shows how `first()` can be combined with `array()` to get the +first element from a dynamically constructed array containing mixed data types. + +```yaml +# first.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Chained Example + type: Microsoft.DSC.Debug/Echo + properties: + output: + firstMixed: "[first(array(createArray('a','b'), createObject('k','v')))]" +``` + +```bash +dsc config get --file first.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Chained Example + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + firstMixed: + - a + - b +messages: [] +hadErrors: false +``` + +## Parameters + +### input + +The array or string to extract the first element or character from. + +```yaml +Type: array or string +Required: true +``` + +If the input is an array, the first element is returned with its original data +type preserved. If the input is a string, the first Unicode character is +returned as a new string. Empty arrays and empty strings will result in an +error. + +## Output + +Returns the first element or character. + +```yaml +Type: string | number | array | object +``` + +## Related functions + +- [`array()`][00] - Creates an array from heterogeneous elements +- [`createArray()`][01] - Creates a homogeneous array +- [`indexOf()`][02] - Finds the index of an item in an array + + +[00]: ./array.md +[01]: ./createArray.md +[02]: ./indexOf.md diff --git a/docs/reference/schemas/config/functions/indexOf.md b/docs/reference/schemas/config/functions/indexOf.md new file mode 100644 index 00000000..4d6b17e1 --- /dev/null +++ b/docs/reference/schemas/config/functions/indexOf.md @@ -0,0 +1,192 @@ +--- +description: Reference for the 'indexOf' DSC configuration document function +ms.date: 08/12/2025 +ms.topic: reference +title: indexOf +--- + +# indexOf + +## Synopsis + +Returns the zero-based index of the first occurrence of an item in an array, or -1 if not found. + +## Syntax + +```Syntax +indexOf(, ) +``` + +## Description + +The `indexOf()` function searches an array for a specific item and returns the +zero-based index of the first matching element. If the item is not found, the +function returns `-1`. This is useful for determining the position of elements +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 +- **Arrays**: Deep equality (same length, order, and element values) +- **Objects**: Deep equality (same keys, values, and structure) + +The search always starts from the beginning of the array and returns the index +of the first match found. + +## Examples + +### Example 1 - Locate a specific server in inventory + +This example demonstrates finding the position of a database server within a +server inventory list, which could be useful for ordering deployment operations +or determining server priorities. + +```yaml +# indexOf.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + servers: + type: array + defaultValue: + - web01 + - web02 + - db01 +resources: +- name: Find Server + type: Microsoft.DSC.Debug/Echo + properties: + output: + dbIndex: "[indexOf(parameters('servers'), 'db01')]" +``` + +```bash +dsc config get --file indexOf.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Find Server + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + dbIndex: 2 +messages: [] +hadErrors: false +``` + +### Example 2 - Detect presence of a feature flag object + +This example shows how to search for complex objects within an array, useful +for checking if specific configuration objects or feature flags are present +in a collection. + +```yaml +# indexOf.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + flags: + type: array + defaultValue: [] +resources: +- name: Flag Lookup + type: Microsoft.DSC.Debug/Echo + properties: + output: + hasFeature: "[indexOf(array(createObject('name','Preview'), createObject('name','Beta')), createObject('name','Beta'))]" +``` + +```bash +dsc config get --file indexOf.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Flag Lookup + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + hasFeature: 1 +messages: [] +hadErrors: false +``` + +### Example 3 - Case sensitivity demonstration + +This example illustrates the case-sensitive nature of string comparisons, +showing how exact case matching is required for successful string searches. + +```yaml +# indexOf.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Case Demo + type: Microsoft.DSC.Debug/Echo + properties: + output: + appleLower: "[indexOf(createArray('Apple','Banana'), 'apple')]" + appleExact: "[indexOf(createArray('Apple','Banana'), 'Apple')]" +``` + +```bash +dsc config get --file indexOf.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Case Demo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + appleLower: -1 + appleExact: 0 +messages: [] +hadErrors: false +``` + +## Parameters + +### arrayToSearch + +The array to search within. + +```yaml +Type: array +Required: true +``` + +### itemToFind + +The item to search for within the array. + +```yaml +Type: string, number, array, or object +Required: true +``` + +The item must be one of the four supported data types. The function will +perform type-appropriate equality checking to find matching elements. + +## Output + +Returns the zero-based index of the first matching element, or -1 if not found. + +```yaml +Type: number +``` + +## Related functions + +- [`array()`][00] - Builds a heterogeneous array +- [`createArray()`][01] - Builds a homogeneous array +- [`first()`][02] - Gets the first element of an array +- [`contains()`][03] - Checks if an array, object key, or string contains a value + + +[00]: ./array.md +[01]: ./createArray.md +[02]: ./first.md +[03]: ./contains.md