Skip to content

Commit e57d7e2

Browse files
SteveL-MSFTSteveL-MSFT
authored
Merge pull request #1178 from Gijsreyn/gh-57/main/add-items-function
Add `items()` function
2 parents d311aae + bad0d03 commit e57d7e2

File tree

5 files changed

+442
-0
lines changed

5 files changed

+442
-0
lines changed

‎docs/reference/schemas/config/functions/items.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
description: Reference for the 'items' DSC configuration document function
3+
ms.date: 10/11/2025
4+
ms.topic: reference
5+
title: items
6+
---
7+
8+
## Synopsis
9+
10+
Converts a dictionary object to an array of key-value pairs.
11+
12+
## Syntax
13+
14+
```Syntax
15+
items(inputObject)
16+
```
17+
18+
## Description
19+
20+
The `items()` function converts a dictionary object to an array of key-value pairs.
21+
22+
- Each element in the returned array is an object with two properties: `key` (the
23+
property name) and `value` (the property value).
24+
25+
This function is useful for iterating over object properties in DSC configurations,
26+
especially when used with loops. It's the companion function to [`toObject()`][03],
27+
which converts an array back to an object.
28+
29+
## Examples
30+
31+
### Example 1 - Convert simple object to array
32+
33+
This example uses [`createObject()`][00] to create a simple object and converts it
34+
to an array of key-value pairs.
35+
36+
```yaml
37+
# items.example.1.dsc.config.yaml
38+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
39+
resources:
40+
- name: Echo
41+
type: Microsoft.DSC.Debug/Echo
42+
properties:
43+
output: "[items(createObject('a', 1, 'b', 2, 'c', 3))]"
44+
```
45+
46+
```bash
47+
dsc config get --file items.example.1.dsc.config.yaml
48+
```
49+
50+
```yaml
51+
results:
52+
- name: Echo
53+
type: Microsoft.DSC.Debug/Echo
54+
result:
55+
actualState:
56+
output:
57+
- key: a
58+
value: 1
59+
- key: b
60+
value: 2
61+
- key: c
62+
value: 3
63+
messages: []
64+
hadErrors: false
65+
```
66+
67+
### Example 2 - Access keys and values
68+
69+
This example shows how to access the keys and values from the items array using array
70+
indexing.
71+
72+
```yaml
73+
# items.example.2.dsc.config.yaml
74+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
75+
resources:
76+
- name: Echo
77+
type: Microsoft.DSC.Debug/Echo
78+
properties:
79+
output: "[items(createObject('firstName', 'John', 'lastName', 'Doe'))[0].key]"
80+
```
81+
82+
```bash
83+
dsc config get --file items.example.2.dsc.config.yaml
84+
```
85+
86+
```yaml
87+
results:
88+
- name: Echo
89+
type: Microsoft.DSC.Debug/Echo
90+
result:
91+
actualState:
92+
output: firstName
93+
messages: []
94+
hadErrors: false
95+
```
96+
97+
### Example 3 - Get length of object
98+
99+
This example shows how to use `items()` with [`length()`][01] to count the number of
100+
properties in an object.
101+
102+
```yaml
103+
# items.example.3.dsc.config.yaml
104+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
105+
resources:
106+
- name: Echo
107+
type: Microsoft.DSC.Debug/Echo
108+
properties:
109+
output: "[length(items(createObject('a', 1, 'b', 2, 'c', 3)))]"
110+
```
111+
112+
```bash
113+
dsc config get --file items.example.3.dsc.config.yaml
114+
```
115+
116+
```yaml
117+
results:
118+
- name: Echo
119+
type: Microsoft.DSC.Debug/Echo
120+
result:
121+
actualState:
122+
output: 3
123+
messages: []
124+
hadErrors: false
125+
```
126+
127+
### Example 4 - Handle nested objects
128+
129+
This example demonstrates using `items()` with objects that contain nested objects.
130+
It uses [`length()`][01] and [`copyIndex()`][02] with the `copy` feature to iterate
131+
over each user.
132+
133+
```yaml
134+
# items.example.4.dsc.config.yaml
135+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
136+
parameters:
137+
users:
138+
type: object
139+
defaultValue:
140+
admin:
141+
name: Administrator
142+
role: admin
143+
guest:
144+
name: Guest User
145+
role: guest
146+
resources:
147+
- name: "[format('User-{0}', copyIndex())]"
148+
copy:
149+
name: userLoop
150+
count: "[length(items(parameters('users')))]"
151+
type: Microsoft.DSC.Debug/Echo
152+
properties:
153+
output: "[items(parameters('users'))[copyIndex()].value.name]"
154+
```
155+
156+
```bash
157+
dsc config get --file items.example.4.dsc.config.yaml
158+
```
159+
160+
```yaml
161+
results:
162+
- name: User-0
163+
type: Microsoft.DSC.Debug/Echo
164+
result:
165+
actualState:
166+
output: Administrator
167+
- name: User-1
168+
type: Microsoft.DSC.Debug/Echo
169+
result:
170+
actualState:
171+
output: Guest User
172+
messages: []
173+
hadErrors: false
174+
```
175+
176+
## Parameters
177+
178+
### inputObject
179+
180+
The dictionary object to convert to an array of key-value pairs.
181+
182+
```yaml
183+
Type: object
184+
Required: true
185+
Position: 1
186+
```
187+
188+
## Output
189+
190+
Returns an array where each element is an object with `key` and `value` properties.
191+
192+
```yaml
193+
Type: array
194+
```
195+
196+
## Related functions
197+
198+
- [`createObject()`][00] - Creates an object from key-value pairs
199+
- [`length()`][01] - Returns the number of elements in an array or object
200+
- [`toObject()`][03] - Converts an array of key-value pairs to an object
201+
202+
<!-- Link reference definitions -->
203+
[00]: ./createObject.md
204+
[01]: ./length.md
205+
[02]: ./copyIndex.md
206+
[03]: ./toObject.md

‎dsc/tests/dsc_functions.tests.ps1‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -858,4 +858,47 @@ Describe 'tests for function expressions' {
858858
$out = $config_yaml | dsc config get -f - | ConvertFrom-Json
859859
$out.results[0].result.actualState.output | Should -Be $expected
860860
}
861+
862+
It 'items function converts object to array: <expression>' -TestCases @(
863+
@{ expression = "[length(items(createObject('a', 1, 'b', 2)))]"; expected = 2 }
864+
@{ expression = "[length(items(createObject()))]"; expected = 0 }
865+
@{ expression = "[items(createObject('name', 'John'))[0].key]"; expected = 'name' }
866+
@{ expression = "[items(createObject('name', 'John'))[0].value]"; expected = 'John' }
867+
@{ expression = "[items(createObject('a', 1, 'b', 2, 'c', 3))[1].key]"; expected = 'b' }
868+
@{ expression = "[items(createObject('x', 'hello', 'y', 'world'))[0].value]"; expected = 'hello' }
869+
) {
870+
param($expression, $expected)
871+
872+
$escapedExpression = $expression -replace "'", "''"
873+
$config_yaml = @"
874+
`$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
875+
resources:
876+
- name: Echo
877+
type: Microsoft.DSC.Debug/Echo
878+
properties:
879+
output: '$escapedExpression'
880+
"@
881+
$out = $config_yaml | dsc config get -f - | ConvertFrom-Json
882+
$out.results[0].result.actualState.output | Should -Be $expected
883+
}
884+
885+
It 'items function handles nested values: <expression>' -TestCases @(
886+
@{ expression = "[items(createObject('person', createObject('name', 'John')))[0].value.name]"; expected = 'John' }
887+
@{ expression = "[items(createObject('list', createArray('a','b','c')))[0].value[1]]"; expected = 'b' }
888+
@{ expression = "[length(items(createObject('obj', createObject('x', 1, 'y', 2)))[0].value)]"; expected = 2 }
889+
) {
890+
param($expression, $expected)
891+
892+
$escapedExpression = $expression -replace "'", "''"
893+
$config_yaml = @"
894+
`$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
895+
resources:
896+
- name: Echo
897+
type: Microsoft.DSC.Debug/Echo
898+
properties:
899+
output: '$escapedExpression'
900+
"@
901+
$out = $config_yaml | dsc config get -f - | ConvertFrom-Json
902+
$out.results[0].result.actualState.output | Should -Be $expected
903+
}
861904
}

‎lib/dsc-lib/locales/en-us.toml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -367,6 +367,10 @@ description = "Returns a single array or object with the common elements from th
367367
invoked = "intersection function"
368368
invalidArgType = "All arguments must either be arrays or objects"
369369

370+
[functions.items]
371+
description = "Converts a dictionary object to an array of objects with key and value properties"
372+
notObject = "Argument must be an object"
373+
370374
[functions.indexOf]
371375
description = "Returns the index of the first occurrence of an item in an array"
372376
invoked = "indexOf function"

0 commit comments

Comments
 (0)