Skip to content

Add objectKeys() function #1258

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SteveL-MSFT merged 5 commits into from
Nov 17, 2025
Merged

Add objectKeys() function #1258

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7edd993
Add `objectKeys` function
Gijsreyn Nov 12, 2025
025122a
Merge branch 'PowerShell:main' into gh-57/main/add-objectkey-function
Gijsreyn Nov 14, 2025
cb78424
Update docs
Gijsreyn Nov 14, 2025
d1465cf
Merge branch 'gh-57/main/add-objectkey-function' of https://github.co…
Gijsreyn Nov 14, 2025
131fb26
Remove explicit error catch
Gijsreyn Nov 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
300 changes: 300 additions & 0 deletions docs/reference/schemas/config/functions/objectKeys.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,300 @@
---
description: Reference for the 'objectKeys' DSC configuration document function
ms.date: 11/14/2025
ms.topic: reference
title: objectKeys
---

## Synopsis

Returns an array containing all the keys from an object.

## Syntax

```Syntax
objectKeys(<inputObject>)
```

## Description

The `objectKeys()` function extracts all property names from an object and returns them as
an array of strings. This function is useful for:

- Iterating over object properties when you only need the keys
- Counting the number of properties in an object
- Checking if specific keys exist in an object
- Converting object keys for further processing

The function only returns the top-level keys of the object. For nested objects, only the
outer keys are included in the result.

This function is similar to [`items()`][00], which returns both keys and values, while
`objectKeys()` returns only the keys.

## Examples

### Example 1 - Extract keys from simple object

The following example extracts all keys from a simple object.

```yaml
# objectKeys.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: "[objectKeys(createObject('firstName', 'John', 'lastName', 'Doe', 'age', 30))]"
```

```bash
dsc config get --file objectKeys.example.1.dsc.config.yaml
```

```yaml
results:
- name: Echo
type: Microsoft.DSC.Debug/Echo
result:
actualState:
output:
- firstName
- lastName
- age
messages: []
hadErrors: false
```

### Example 2 - Count object properties

The following example uses `objectKeys()` with [`length()`][01] to count the number of
properties in an object.

```yaml
# objectKeys.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: "[length(objectKeys(createObject('a', 1, 'b', 2, 'c', 3)))]"
```

```bash
dsc config get --file objectKeys.example.2.dsc.config.yaml
```

```yaml
results:
- name: Echo
type: Microsoft.DSC.Debug/Echo
result:
actualState:
output: 3
messages: []
hadErrors: false
```

### Example 3 - Check if key exists

The following example uses `objectKeys()` with [`contains()`][02] to check if a specific
key exists in an object.

```yaml
# objectKeys.example.3.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
parameters:
config:
type: object
defaultValue:
enabled: true
timeout: 30
resources:
- name: Echo
type: Microsoft.DSC.Debug/Echo
properties:
output:
hasEnabled: "[contains(objectKeys(parameters('config')), 'enabled')]"
hasDebug: "[contains(objectKeys(parameters('config')), 'debug')]"
```

```bash
dsc config get --file objectKeys.example.3.dsc.config.yaml
```

```yaml
results:
- name: Echo
type: Microsoft.DSC.Debug/Echo
result:
actualState:
output:
hasEnabled: true
hasDebug: false
messages: []
hadErrors: false
```

### Example 4 - Iterate over keys with copy loop

The following example uses `objectKeys()` to iterate over object properties using the
[`copy`][03] feature.

```yaml
# objectKeys.example.4.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
parameters:
settings:
type: object
defaultValue:
debug: false
logLevel: info
maxRetries: 3
resources:
- name: "[format('Setting-{0}', copyIndex())]"
copy:
name: settingsLoop
count: "[length(objectKeys(parameters('settings')))]"
type: Microsoft.DSC.Debug/Echo
properties:
output: "[objectKeys(parameters('settings'))[copyIndex()]]"
```

```bash
dsc config get --file objectKeys.example.4.dsc.config.yaml
```

```yaml
results:
- name: Setting-0
type: Microsoft.DSC.Debug/Echo
result:
actualState:
output: debug
- name: Setting-1
type: Microsoft.DSC.Debug/Echo
result:
actualState:
output: logLevel
- name: Setting-2
type: Microsoft.DSC.Debug/Echo
result:
actualState:
output: maxRetries
messages: []
hadErrors: false
```

### Example 5 - Top-level keys only

The following example demonstrates that `objectKeys()` only returns top-level keys, even
when the object contains nested objects.

```yaml
# objectKeys.example.5.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Echo
type: Microsoft.DSC.Debug/Echo
properties:
output: "[objectKeys(createObject('user', createObject('name', 'John', 'age', 30), 'role', 'admin'))]"
```

```bash
dsc config get --file objectKeys.example.5.dsc.config.yaml
```

```yaml
results:
- name: Echo
type: Microsoft.DSC.Debug/Echo
result:
actualState:
output:
- user
- role
messages: []
hadErrors: false
```

### Example 6 - Empty object

The following example shows that `objectKeys()` returns an empty array for an empty object.

```yaml
# objectKeys.example.6.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Echo
type: Microsoft.DSC.Debug/Echo
properties:
output:
keys: "[objectKeys(createObject())]"
isEmpty: "[equals(length(objectKeys(createObject())), 0)]"
```

```bash
dsc config get --file objectKeys.example.6.dsc.config.yaml
```

```yaml
results:
- name: Echo
type: Microsoft.DSC.Debug/Echo
result:
actualState:
output:
keys: []
isEmpty: true
messages: []
hadErrors: false
```

## Parameters

### inputObject

The object from which to extract the keys.

```yaml
Type: object
Required: true
Position: 1
```

## Output

Returns an array of strings, where each string is a property name (key) from the input
object. The array contains only the top-level keys.

```yaml
Type: array
```

## Error conditions

The function will return an error in the following cases:

- **Not an object**: The input is not an object (e.g., string, number, array, null)

## Notes

- The function only returns top-level keys; nested object keys are not included
- For empty objects, the function returns an empty array
- The order of keys in the returned array follows JSON object property ordering
- Key names are always returned as strings
- To get both keys and values, use [`items()`][00] instead

## Related functions

- [`items()`][00] - Converts an object to an array of key-value pairs
- [`createObject()`][04] - Creates an object from key-value pairs
- [`length()`][01] - Returns the number of elements in an array
- [`contains()`][02] - Checks if an array contains a specific value

<!-- Link reference definitions -->
[00]: ./items.md
[01]: ./length.md
[02]: ./contains.md
[03]: ../document/copy.md
[04]: ./createObject.md
40 changes: 40 additions & 0 deletions dsc/tests/dsc_functions.tests.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -958,6 +958,46 @@ Describe 'tests for function expressions' {
$out.results[0].result.actualState.output | Should -Be $expected
}

It 'objectKeys function returns array of keys: <expression>' -TestCases @(
@{ expression = "[length(objectKeys(createObject('a', 1, 'b', 2, 'c', 3)))]"; expected = 3 }
@{ expression = "[length(objectKeys(createObject()))]"; expected = 0 }
@{ expression = "[objectKeys(createObject('name', 'John'))[0]]"; expected = 'name' }
@{ expression = "[length(objectKeys(createObject('x', 1, 'y', 2)))]"; expected = 2 }
) {
param($expression, $expected)

$escapedExpression = $expression -replace "'", "''"
$config_yaml = @"
`$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Echo
type: Microsoft.DSC.Debug/Echo
properties:
output: '$escapedExpression'
"@
$out = $config_yaml | dsc config get -f - | ConvertFrom-Json
$out.results[0].result.actualState.output | Should -Be $expected
}

It 'objectKeys function works with nested objects: <expression>' -TestCases @(
@{ expression = "[objectKeys(createObject('person', createObject('name', 'John')))[0]]"; expected = 'person' }
@{ expression = "[length(objectKeys(createObject('a', createArray(1,2,3), 'b', 'text')))]"; expected = 2 }
) {
param($expression, $expected)

$escapedExpression = $expression -replace "'", "''"
$config_yaml = @"
`$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Echo
type: Microsoft.DSC.Debug/Echo
properties:
output: '$escapedExpression'
"@
$out = $config_yaml | dsc config get -f - | ConvertFrom-Json
$out.results[0].result.actualState.output | Should -Be $expected
}

It 'tryGet() function works for: <expression>' -TestCases @(
@{ expression = "[tryGet(createObject('a', 1, 'b', 2), 'a')]"; expected = 1 }
@{ expression = "[tryGet(createObject('a', 1, 'b', 2), 'c')]"; expected = $null }
Expand Down
3 changes: 3 additions & 0 deletions lib/dsc-lib/locales/en-us.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -448,6 +448,9 @@ invoked = "not function"
description = "Returns a null value"
invoked = "null function"

[functions.objectKeys]
description = "Returns the keys from an object, where an object is a collection of key-value pairs"

[functions.or]
description = "Evaluates if any arguments are true"
invoked = "or function"
Expand Down
2 changes: 2 additions & 0 deletions lib/dsc-lib/src/functions/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ pub mod mod_function;
pub mod mul;
pub mod not;
pub mod null;
pub mod object_keys;
pub mod or;
pub mod parameters;
pub mod parse_cidr;
Expand Down Expand Up @@ -189,6 +190,7 @@ impl FunctionDispatcher {
Box::new(mul::Mul{}),
Box::new(not::Not{}),
Box::new(null::Null{}),
Box::new(object_keys::ObjectKeys{}),
Box::new(or::Or{}),
Box::new(parameters::Parameters{}),
Box::new(parse_cidr::ParseCidr{}),
Expand Down
Loading