diff --git a/docs/reference/schemas/config/functions/copy.md b/docs/reference/schemas/config/functions/copy.md new file mode 100644 index 000000000..206d8ab2d --- /dev/null +++ b/docs/reference/schemas/config/functions/copy.md @@ -0,0 +1,220 @@ +--- +description: Reference for the 'copy' DSC configuration document resource loop +ms.date: 02/28/2025 +ms.topic: reference +title: copy +--- + +# copy + +## Synopsis + +Defines a loop to create multiple instances of a resource. + +## Syntax + +```Syntax +copy: + name: + count: +``` + +## Description + +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. + +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] +function within the resource definition to access the current iteration index +and create unique names or property values for each instance. + +> [!NOTE] +> The `mode` and `batchSize` properties are not currently supported and will +> result in an error if used. + +## Examples + +### Example 1 - Create multiple Echo resources + +This example demonstrates the basic usage of `copy` to create three instances +of a Debug Echo resource. + +```yaml +# copy.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Echo-{0}', copyIndex())]" + copy: + name: echoLoop + count: 3 + type: Microsoft.DSC.Debug/Echo + properties: + output: "Hello DSC" +``` + +```bash +dsc config get --file copy.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo-0 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Hello DSC +- name: Echo-1 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Hello DSC +- name: Echo-2 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Hello DSC +messages: [] +hadErrors: false +``` + +### Example 2 - Using copyIndex with offset + +This example demonstrates using [`copyIndex()`][01] with an offset to start +numbering from a different value. + +```yaml +# copy.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Service-{0}', copyIndex(100))]" + copy: + name: serviceLoop + count: 3 + type: Microsoft.DSC.Debug/Echo + properties: + output: "Service instance" +``` + +```bash +dsc config get --file copy.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Service-100 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Service instance +- name: Service-101 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Service instance +- name: Service-102 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Service instance +messages: [] +hadErrors: false +``` + +### Example 3 - Using named loop references + +This example shows how to reference a specific loop by name when using +[`copyIndex()`][01]. + +```yaml +# copy.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Resource-{0}', copyIndex('mainLoop'))]" + copy: + name: mainLoop + count: 2 + type: Microsoft.DSC.Debug/Echo + properties: + output: "From main loop" +``` + +```bash +dsc config get --file copy.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Resource-0 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: From main loop +- name: Resource-1 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: From main loop +messages: [] +hadErrors: false +``` + +## Properties + +### name + +The name of the copy loop. This name can be used with the [`copyIndex()`][01] +function to reference the current iteration index of this specific loop. + +```yaml +Type: string +Required: true +``` + +### count + +The number of iterations to perform. Must be a non-negative integer. If set to +0, no instances of the resource are created. + +```yaml +Type: integer +Required: true +Minimum: 0 +``` + +### mode + +> [!WARNING] +> The `mode` property is not currently supported and will result in an error +> if used. + +This property is reserved for future implementation to specify whether resources +should be created serially or in parallel. + +### batchSize + +> [!WARNING] +> The `batchSize` property is not currently supported and will result in an +> error if used. + +This property is reserved for future implementation to specify how many +resources to create in each batch when using parallel mode. + +## Limitations + +The current implementation has the following limitations: + +- **Variables and properties**: Copy loops for variables and properties are not + yet supported. +- **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 + +- [`copyIndex()`][01] - Returns the current iteration index of a copy loop. + + +[01]: ./copyIndex.md diff --git a/docs/reference/schemas/config/functions/copyIndex.md b/docs/reference/schemas/config/functions/copyIndex.md new file mode 100644 index 000000000..56a61ddf4 --- /dev/null +++ b/docs/reference/schemas/config/functions/copyIndex.md @@ -0,0 +1,218 @@ +--- +description: Reference for the 'copyIndex' DSC configuration document function +ms.date: 02/28/2025 +ms.topic: reference +title: copyIndex +--- + +# copyIndex + +## Synopsis + +Returns the current iteration index of a copy loop. + +## Syntax + +```Syntax +copyIndex() +copyIndex() +copyIndex('') +copyIndex('', ) +``` + +## Description + +The `copyIndex()` function returns the current iteration index of a copy loop. +This function can only be used within resources that have a `copy` property +defined. The function is necessary for creating unique names and property +values for each instance created by the copy loop. + +The index starts at 0 for the first iteration and increments by 1 for each +subsequent iteration. You can add an offset to shift the starting number, or +reference a specific loop by name when multiple copy loops are present. + +## Examples + +### Example 1 - Basic copyIndex usage + +This example shows the basic usage of `copyIndex()` to create unique resource +names. + +```yaml +# copyIndex.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Resource-{0}', copyIndex())]" + copy: + name: basicLoop + count: 3 + type: Microsoft.DSC.Debug/Echo + properties: + output: "Hello DSC" +``` +```bash +dsc config get --file copyIndex.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Resource-0 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Hello World" +- name: Resource-1 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Hello World" +- name: Resource-2 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Hello World" +messages: [] +hadErrors: false +``` +### Example 2 - Using copyIndex with offset +This example demonstrates using an offset to start numbering from a different +value. +```yaml +# copyIndex.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Server-{0}', copyIndex(10))]" + copy: + name: serverLoop + count: 3 + type: Microsoft.DSC.Debug/Echo + properties: + output: "Server instance starting from 10 till 12" +``` +```bash +dsc config get --file copyIndex.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Server-10 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Server instance starting from 10 till 12" +- name: Server-11 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Server instance starting from 10 till 12" +- name: Server-12 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Server instance starting from 10 till 12" +messages: [] +hadErrors: false +``` +### Example 3 - Using copyIndex with loop name +This example shows how to reference a specific loop by name. +```yaml +# copyIndex.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Item-{0}', copyIndex('itemLoop'))]" + copy: + name: itemLoop + count: 1 + type: Microsoft.DSC.Debug/Echo + properties: + output: "Item from loop" +``` +```bash +dsc config get --file copyIndex.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Item-0 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Item from loop" +messages: [] +hadErrors: false +``` +### Example 4 - Using copyIndex with loop name and offset +This example combines both loop name and offset parameters. +```yaml +# copyIndex.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Database-{0}', copyIndex('dbLoop', 100))]" + copy: + name: dbLoop + count: 2 + type: Microsoft.DSC.Debug/Echo + properties: + output: "Database instance" +``` +```bash +dsc config get --file copyIndex.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Database-100 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Database instance" +- name: Database-101 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Database instance" +messages: [] +hadErrors: false +``` +## Parameters +### offset +An optional integer offset to add to the current index. The offset must be a +non-negative number. +```yaml +Type: integer +Required: false +Minimum: 0 +``` +### loopName +An optional string specifying the name of the copy loop to reference. This is +useful when you have multiple copy loops and need to reference a specific one. +```yaml +Type: string +Required: false +``` +## Output +The `copyIndex()` function returns an integer representing the current iteration +index, optionally adjusted by the offset. + +```yaml +Type: integer +``` + +## Error Conditions + +The `copyIndex()` function will return an error in the following situations: + +- **Used outside copy loop**: The function can only be used within resources + that have a `copy` property defined. +- **Negative offset**: The offset parameter must be non-negative. +- **Invalid loop name**: If a loop name is specified but no loop with that + name exists. +- **Invalid arguments**: If the arguments provided are not of the expected + types. + +## Related Properties + +- [`copy`][01] - Defines a loop to create multiple instances of a resource. + + +[01]: ./copy.md \ No newline at end of file diff --git a/docs/reference/schemas/config/functions/overview.md b/docs/reference/schemas/config/functions/overview.md index dd8341359..236b8a6db 100644 --- a/docs/reference/schemas/config/functions/overview.md +++ b/docs/reference/schemas/config/functions/overview.md @@ -603,6 +603,7 @@ The following list of functions operate on integer values or arrays of integer v The following list of 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. @@ -631,6 +632,7 @@ The following list of functions create or convert values of a given type: [add]: ./add.md [base64]: ./base64.md [concat]: ./concat.md +[copyIndex]: ./copyIndex.md [createArray]: ./createArray.md [div]: ./div.md [envvar]: ./envvar.md