Skip to content

Commit 79633e1

Browse files
SteveL-MSFTSteveL-MSFT
authored
Merge pull request #1040 from Gijsreyn/add-string-function
Add string function
2 parents 18fd542 + d82f987 commit 79633e1

File tree

5 files changed

+380
-0
lines changed

5 files changed

+380
-0
lines changed

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

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
---
2+
description: Reference for the 'string' DSC configuration document function
3+
ms.date: 08/09/2025
4+
ms.topic: reference
5+
title: string
6+
---
7+
8+
# string
9+
10+
## Synopsis
11+
12+
Converts a value to a string representation.
13+
14+
## Syntax
15+
16+
```Syntax
17+
string(<value>)
18+
```
19+
20+
## Description
21+
22+
The `string()` function converts a value of any type to its string
23+
representation. This is useful for formatting output, concatenating values, or
24+
ensuring consistent data types. Arrays and objects are converted to JSON
25+
strings, while primitive types are converted to their standard string
26+
representations.
27+
28+
## Examples
29+
30+
### Example 1 - Convert integers to strings
31+
32+
The following example shows how to convert numbers to strings for display
33+
purposes.
34+
35+
```yaml
36+
# string.example.1.dsc.config.yaml
37+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
38+
parameters:
39+
serverCount:
40+
type: int
41+
defaultValue: 42
42+
memorySize:
43+
type: int
44+
defaultValue: 16
45+
resources:
46+
- name: Convert numbers
47+
type: Microsoft.DSC.Debug/Echo
48+
properties:
49+
output:
50+
serverCountString: "[string(parameters('serverCount'))]"
51+
memorySizeString: "[string(parameters('memorySize'))]"
52+
literalNumber: "[string(123)]"
53+
```
54+
55+
```bash
56+
dsc config get --file string.example.1.dsc.config.yaml
57+
```
58+
59+
```yaml
60+
results:
61+
- name: Convert numbers
62+
type: Microsoft.DSC.Debug/Echo
63+
result:
64+
actualState:
65+
output:
66+
serverCountString: '42'
67+
memorySizeString: '16'
68+
literalNumber: '123'
69+
messages: []
70+
hadErrors: false
71+
```
72+
73+
### Example 2 - Convert arrays and objects to JSON strings
74+
75+
The following example shows how arrays and objects are converted to JSON
76+
strings.
77+
78+
```yaml
79+
# string.example.2.dsc.config.yaml
80+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
81+
parameters:
82+
serverList:
83+
type: array
84+
defaultValue:
85+
- web01
86+
- web02
87+
- db01
88+
config:
89+
type: object
90+
defaultValue:
91+
timeout: 30
92+
retries: 3
93+
enabled: true
94+
resources:
95+
- name: Convert collections
96+
type: Microsoft.DSC.Debug/Echo
97+
properties:
98+
output:
99+
serversJson: "[string(parameters('serverList'))]"
100+
configJson: "[string(parameters('config'))]"
101+
arrayLiteral: "[string(createArray('a', 'b'))]"
102+
```
103+
104+
```bash
105+
dsc config get --file string.example.3.dsc.config.yaml
106+
```
107+
108+
```yaml
109+
results:
110+
- metadata:
111+
Microsoft.DSC:
112+
duration: PT0.1452881S
113+
name: Convert collections
114+
type: Microsoft.DSC.Debug/Echo
115+
result:
116+
actualState:
117+
output:
118+
serversJson: '["web01","web02","db01"]'
119+
configJson: '{"timeout":30,"retries":3,"enabled":true}'
120+
arrayLiteral: '["a","b"]'
121+
messages: []
122+
hadErrors: false
123+
```
124+
125+
### Example 3 - Building formatted messages
126+
127+
The following example shows a practical use case for building formatted
128+
messages using string conversion.
129+
130+
```yaml
131+
# string.example.3.dsc.config.yaml
132+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
133+
parameters:
134+
deploymentId:
135+
type: int
136+
defaultValue: 12345
137+
isProduction:
138+
type: bool
139+
defaultValue: false
140+
serverCount:
141+
type: int
142+
defaultValue: 3
143+
resources:
144+
- name: Build status message
145+
type: Microsoft.DSC.Debug/Echo
146+
properties:
147+
output:
148+
deploymentInfo: "[concat('Deployment ', string(parameters('deploymentId')), ' running in ', if(parameters('isProduction'), 'production', 'development'), ' mode')]"
149+
serverMessage: "[concat('Managing ', string(parameters('serverCount')), ' server(s)')]"
150+
statusFlag: "[concat('Production: ', string(parameters('isProduction')))]"
151+
```
152+
153+
```bash
154+
dsc config get --file string.example.4.dsc.config.yaml
155+
```
156+
157+
```yaml
158+
results:
159+
- name: Build status message
160+
type: Microsoft.DSC.Debug/Echo
161+
result:
162+
actualState:
163+
output:
164+
deploymentInfo: Deployment 12345 running in development mode
165+
serverMessage: Managing 3 server(s)
166+
statusFlag: 'Production: false'
167+
messages: []
168+
hadErrors: false
169+
```
170+
171+
### Example 4 - String conversion for logging
172+
173+
The following example demonstrates converting various data types for logging
174+
purposes.
175+
176+
```yaml
177+
# string.example.4.dsc.config.yaml
178+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
179+
parameters:
180+
timestamp:
181+
type: int
182+
defaultValue: 1691596800
183+
errorCode:
184+
type: int
185+
defaultValue: 404
186+
metadata:
187+
type: object
188+
defaultValue:
189+
source: "api"
190+
level: "error"
191+
resources:
192+
- name: Generate log entry
193+
type: Microsoft.DSC.Debug/Echo
194+
properties:
195+
output:
196+
logEntry: "[concat('[', string(parameters('timestamp')), '] ERROR ', string(parameters('errorCode')), ': ', string(parameters('metadata')))]"
197+
```
198+
199+
```bash
200+
dsc config get --file string.example.5.dsc.config.yaml
201+
```
202+
203+
```yaml
204+
results:
205+
- name: Generate log entry
206+
type: Microsoft.DSC.Debug/Echo
207+
result:
208+
actualState:
209+
output:
210+
logEntry: '[1691596800] ERROR 404: {"level":"error","source":"api"}'
211+
messages: []
212+
hadErrors: false
213+
```
214+
215+
## Parameters
216+
217+
### value
218+
219+
The value to convert to a string.
220+
221+
```yaml
222+
Type: [string, number, bool, null, array, object]
223+
Required: true
224+
```
225+
226+
The `string()` function accepts exactly one input value of any type. The
227+
conversion behavior depends on the input type:
228+
229+
- **String**: Returns the string unchanged
230+
- **Number**: Converts to decimal string representation
231+
- **Boolean**: Converts to "true" or "false"
232+
- **Null**: Converts to "null"
233+
- **Array**: Converts to JSON array string
234+
- **Object**: Converts to JSON object string
235+
236+
## Output
237+
238+
The `string()` function returns the string representation of the input value.
239+
240+
```yaml
241+
Type: string
242+
```
243+
244+
## Related functions
245+
246+
- [`concat()`][00] - Concatenates strings together
247+
- [`int()`][01] - Converts a string to an integer
248+
- [`bool()`][02] - Converts a string to a boolean
249+
- [`base64()`][03] - Encodes a string to Base64 format
250+
- [`length()`][04] - Returns the length of a string
251+
252+
<!-- Link reference definitions -->
253+
[00]: ./concat.md
254+
[01]: ./int.md
255+
[02]: ./bool.md
256+
[03]: ./base64.md
257+
[04]: ./length.md

‎dsc/tests/dsc_functions.tests.ps1

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -320,4 +320,27 @@ Describe 'tests for function expressions' {
320320
$LASTEXITCODE | Should -Be 0 -Because (Get-Content $TestDrive/error.log -Raw)
321321
$out.results[0].result.actualState.output | Should -BeExactly $expected
322322
}
323+
324+
It 'string function works for: <expression>' -TestCases @(
325+
@{ expression = "[string('hello')]"; expected = 'hello' }
326+
@{ expression = "[string(123)]"; expected = '123' }
327+
@{ expression = "[string(true)]"; expected = 'true' }
328+
@{ expression = "[string(null())]"; expected = 'null' }
329+
@{ expression = "[string(createArray('a', 'b'))]"; expected = '["a","b"]' }
330+
@{ expression = "[string(createObject('a', 1))]"; expected = '{"a":1}' }
331+
) {
332+
param($expression, $expected)
333+
334+
$config_yaml = @"
335+
`$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
336+
resources:
337+
- name: Echo
338+
type: Microsoft.DSC.Debug/Echo
339+
properties:
340+
output: "$expression"
341+
"@
342+
$out = dsc -l trace config get -i $config_yaml 2>$TestDrive/error.log | ConvertFrom-Json
343+
$LASTEXITCODE | Should -Be 0 -Because (Get-Content $TestDrive/error.log -Raw)
344+
($out.results[0].result.actualState.output | Out-String) | Should -BeExactly ($expected | Out-String)
345+
}
323346
}

‎dsc_lib/locales/en-us.toml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -389,6 +389,9 @@ secretNotFound = "Secret '%{name}' not found"
389389
description = "Checks if a string starts with a specific prefix"
390390
invoked = "startsWith function"
391391

392+
[functions.string]
393+
description = "Converts a value to a string"
394+
392395
[functions.sub]
393396
description = "Subtracts the second number from the first"
394397
invoked = "sub function"

‎dsc_lib/src/functions/mod.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ pub mod reference;
4747
pub mod resource_id;
4848
pub mod secret;
4949
pub mod starts_with;
50+
pub mod string;
5051
pub mod sub;
5152
pub mod system_root;
5253
pub mod r#true;
@@ -152,6 +153,7 @@ impl FunctionDispatcher {
152153
Box::new(resource_id::ResourceId{}),
153154
Box::new(secret::Secret{}),
154155
Box::new(starts_with::StartsWith{}),
156+
Box::new(string::StringFn{}),
155157
Box::new(sub::Sub{}),
156158
Box::new(system_root::SystemRoot{}),
157159
Box::new(r#true::True{}),

0 commit comments

Comments
 (0)