Skip to content

Commit c02ff0f

Browse files
michaeltlombardimichaeltlombardi
committed
(DOCS) Update config function reference for 3.1.0
This change adds reference documentation for the `equals()` and `if()` functions and expands the documentation for the `format()` function.
1 parent b6b151c commit c02ff0f

File tree

3 files changed

+388
-14
lines changed

3 files changed

+388
-14
lines changed

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

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
description: Reference for the 'equals' DSC configuration document function
3+
ms.date: 07/02/2025
4+
ms.topic: reference
5+
title: equals
6+
---
7+
8+
# equals
9+
10+
## Synopsis
11+
12+
Checks whether two values are identical.
13+
14+
## Syntax
15+
16+
```Syntax
17+
equals(<inputValue>)
18+
```
19+
20+
## Description
21+
22+
The `equals()` function checks whether two values are identical, returning `true` if they are and
23+
otherwise `false`. You can use this function to compare two values of the same data type. If the
24+
values are different types, like a string and an integer, DSC returns `false` for this function.
25+
26+
## Examples
27+
28+
### Example 1 - Compare two strings
29+
30+
The following example shows how you can use the function to compare two strings.
31+
32+
```yaml
33+
# equals.example.1.dsc.config.yaml
34+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
35+
resources:
36+
- name: Compare strings
37+
type: Microsoft.DSC.Debug/Echo
38+
properties:
39+
output:
40+
sameCase: "[equals('a', 'a')]"
41+
differentCase: "[equals('a', 'A')]"
42+
differentLetters: "[equals('a', 'b')]"
43+
```
44+
45+
```bash
46+
dsc config get --file equals.example.1.dsc.config.yaml
47+
```
48+
49+
```yaml
50+
results:
51+
- name: Compare strings
52+
type: Microsoft.DSC.Debug/Echo
53+
result:
54+
actualState:
55+
output:
56+
sameCase: true
57+
differentCase: false
58+
differentLetters: false
59+
messages: []
60+
hadErrors: false
61+
```
62+
63+
### Example 2 - Compare two integers
64+
65+
The following example shows how you can use the function to compare two integers.
66+
67+
```yaml
68+
# equals.example.2.dsc.config.yaml
69+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
70+
resources:
71+
- name: Compare integers
72+
type: Microsoft.DSC.Debug/Echo
73+
properties:
74+
output:
75+
sameInteger: "[equals(1, 1)]"
76+
differentInteger: "[equals(1, 2)]"
77+
```
78+
79+
```bash
80+
dsc config get --file equals.example.2.dsc.config.yaml
81+
```
82+
83+
```yaml
84+
results:
85+
- name: Compare integers
86+
type: Microsoft.DSC.Debug/Echo
87+
result:
88+
actualState:
89+
output:
90+
sameInteger: true
91+
differentInteger: false
92+
sameFloat: true
93+
differentFloat: false
94+
integerAndFloat: ?
95+
messages: []
96+
hadErrors: false
97+
```
98+
99+
### Example 3 - Compare two arrays
100+
101+
The following example shows how you can use the function to compare two arrays.
102+
103+
```yaml
104+
# equals.example.3.dsc.config.yaml
105+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
106+
resources:
107+
- name: Compare arrays
108+
type: Microsoft.DSC.Debug/Echo
109+
properties:
110+
output:
111+
sameStringsAndOrder: >-
112+
[equals(
113+
createArray('a', 'b', 'c'),
114+
createArray('a', 'b', 'c')
115+
)]
116+
sameStringsDifferentOrder: >-
117+
[equals(
118+
createArray('a', 'b', 'c'),
119+
createArray('c', 'b', 'a')
120+
)]
121+
sameNumbers: >-
122+
[equals(
123+
createArray(1, 2, 3),
124+
createArray(1, 2, 3)
125+
)]
126+
sameNestedArrays: >-
127+
[equals(
128+
createArray(
129+
createArray('a', 'b', 'c'),
130+
createArray(1, 2, 3)
131+
),
132+
createArray(
133+
createArray('a', 'b', 'c'),
134+
createArray(1, 2, 3)
135+
)
136+
)]
137+
```
138+
139+
```bash
140+
dsc config get --file equals.example.3.dsc.config.yaml
141+
```
142+
143+
```yaml
144+
results:
145+
- name: Compare arrays
146+
type: Microsoft.DSC.Debug/Echo
147+
result:
148+
actualState:
149+
output:
150+
sameStringsAndOrder: true
151+
sameStringsDifferentOrder: false
152+
sameNumbers: true
153+
sameNestedArrays: true
154+
messages: []
155+
hadErrors: false
156+
```
157+
158+
## Parameters
159+
160+
### inputValue
161+
162+
The `equals()` function expects exactly two input values of the same type. Separate each value with
163+
a comma. If the type of the second input value is different from the first value, DSC returns an
164+
error for the function.
165+
166+
String comparisons are case-sensitive. Array comparisons are position-sensitive.
167+
168+
```yaml
169+
Type: [integer, string, object, array]
170+
Required: true
171+
MinimumCount: 2
172+
MaximumCount: 2
173+
```
174+
175+
## Output
176+
177+
The `equals()` function returns `true` if the input values are the same and otherwise `false`.
178+
179+
```yaml
180+
Type: bool
181+
```
182+
183+
<!-- Link reference definitions -->

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

Lines changed: 95 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,32 @@ format(<formatString>, <arg1>, <arg2>, ...)
2121

2222
The `format()` function returns a string that includes formatted values using a template and
2323
placeholders. Each placeholder in the template string is replaced with the corresponding argument
24-
value. Placeholders are specified with curly braces around the zero-based index of the argument.
24+
value.
25+
26+
### Placeholder syntax
27+
28+
Placeholders must be defined with the following syntax:
29+
30+
```Syntax
31+
{<index>[:<formatSpecifier>]}
32+
```
33+
34+
Every placeholder must specify the zero-based index of the argument.
35+
36+
This function supports a subset of format specifiers for controlling how data is formatted in the
37+
string. To use a format specifier, define a placeholder followed by a colon and then a specifier.
38+
39+
The following table defines the supported format specifiers and the data types they're valid for.
40+
If you use a format specifier with an invalid data type, DSC raises an error.
41+
42+
| Specifier | Format | Valid Types |
43+
|:---------:|:----------------------|:------------|
44+
| `b` | Binary | `integer` |
45+
| `e` | Lowercase exponential | `integer` |
46+
| `E` | Uppercase exponential | `integer` |
47+
| `o` | Octal | `integer` |
48+
| `e` | Lowercase hexadecimal | `integer` |
49+
| `E` | Uppercase hexadecimal | `integer` |
2550

2651
## Examples
2752

@@ -54,13 +79,60 @@ messages: []
5479
hadErrors: false
5580
```
5681
57-
### Example 2 - Format a string with parameters
82+
### Example 2 - Format specifiers
5883
59-
The configuration uses other functions within the `format()` function to build a dynamic message.
84+
This example demonstrates formatting every supported data type and format specifier.
6085
6186
```yaml
6287
# format.example.2.dsc.config.yaml
6388
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
89+
resources:
90+
- name: descriptive resource name
91+
type: Microsoft.DSC.Debug/Echo
92+
properties:
93+
output:
94+
string: "[format('{0} {1}', 'hello', 'world')]"
95+
boolean: "[format('{0} or {1}', true, false)]"
96+
integer:
97+
binary: "[format('{0} => {0:b}', 123)]"
98+
octal: "[format('{0} => {0:o}', 123)]"
99+
lowercaseHex: "[format('{0} => {0:x}', 123)]"
100+
uppercaseHex: "[format('{0} => {0:X}', 123)]"
101+
lowercaseExponent: "[format('{0} => {0:e}', 123)]"
102+
uppercaseExponent: "[format('{0} => {0:E}', 123)]"
103+
```
104+
105+
```bash
106+
dsc config get --file format.example.2.dsc.config.yaml
107+
```
108+
109+
```yaml
110+
results:
111+
- name: descriptive resource name
112+
type: Microsoft.DSC.Debug/Echo
113+
result:
114+
actualState:
115+
output:
116+
string: hello world
117+
boolean: true or false
118+
integer:
119+
binary: 1111011
120+
octal: 173
121+
lowercaseHex: 7b
122+
uppercaseHex: 7B
123+
lowercaseExponent: 1.23e2
124+
uppercaseExponent: 1.23E2
125+
messages: []
126+
hadErrors: false
127+
```
128+
129+
### Example 3 - Format a string with parameters
130+
131+
The configuration uses other functions within the `format()` function to build a dynamic message.
132+
133+
```yaml
134+
# format.example.3.dsc.config.yaml
135+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
64136
parameters:
65137
username:
66138
type: string
@@ -75,19 +147,22 @@ resources:
75147
- name: Echo dynamic formatted string
76148
type: Microsoft.DSC.Debug/Echo
77149
properties:
78-
output: "[format('Hello, {0}! The time is {1}:{2}.', parameters('username'), parameters('hour'), parameters('minute'))]"
150+
output: >-
151+
[format(
152+
'Hello, {0}! The time is {1}:{2}.',
153+
parameters('username'),
154+
parameters('hour'),
155+
parameters('minute')
156+
)]
79157
```
80158

81159
```bash
82-
dsc --file format.example.2.dsc.config.yaml config get
160+
dsc --file format.example.3.dsc.config.yaml config get
83161
```
84162

85163
```yaml
86164
results:
87-
- metadata:
88-
Microsoft.DSC:
89-
duration: PT0.0185508S
90-
name: Echo dynamic formatted string
165+
- name: Echo dynamic formatted string
91166
type: Microsoft.DSC.Debug/Echo
92167
result:
93168
actualState:
@@ -101,7 +176,13 @@ hadErrors: false
101176
### formatString
102177

103178
The `format()` function requires a template string that includes placeholders for argument values.
104-
Placeholders use the format `{n}`, where `n` is the zero-based index of the argument to insert.
179+
180+
Placeholders use the zero-based index of the function arguments. You can reference the same
181+
argument any number of times. If DSC can't resolve the placeholder index to an argument, DSC raises
182+
an error.
183+
184+
For more information about the syntax for defining placeholders, see
185+
[Placeholder syntax](#placeholder-syntax).
105186

106187
```yaml
107188
Type: string
@@ -112,18 +193,18 @@ MaximumCount: 1
112193

113194
### arguments
114195

115-
The function accepts one or more arguments of any type to insert into the formatted string.
196+
The function accepts one or more arguments to insert into the formatted string.
116197

117198
```yaml
118-
Type: any
199+
Type: [boolean, integer, string]
119200
Required: true
120201
MinimumCount: 1
121-
MaximumCount: unlimited
202+
MaximumCount: 18446744073709551615
122203
```
123204

124205
## Output
125206

126-
The `format()` function returns a string where each placeholder in the **formatString** is replaced
207+
The `format()` function returns a string where each placeholder in the `formatString` is replaced
127208
with the corresponding argument value.
128209

129210
```yaml

0 commit comments

Comments
 (0)