Skip to content

Commit 45b8d90

Browse files
GijsreynGijsreyn
committed
Add dataUri and dataUriToString functions with documentation and tests
1 parent 8503b80 commit 45b8d90

File tree

8 files changed

+666
-0
lines changed

8 files changed

+666
-0
lines changed

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

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
description: Reference for the 'dataUri' DSC configuration document function
3+
ms.date: 12/20/2025
4+
ms.topic: reference
5+
title: dataUri
6+
---
7+
8+
# dataUri
9+
10+
## Synopsis
11+
12+
Converts a value to a data URI.
13+
14+
## Syntax
15+
16+
```Syntax
17+
dataUri(<stringToConvert>)
18+
```
19+
20+
## Description
21+
22+
The `dataUri()` function converts a string value to a [data URI][01] format. The function encodes
23+
the input string as base64 and returns it as a data URI with the `text/plain` media type and
24+
`utf8` charset.
25+
26+
Data URIs are useful for embedding small text content directly in configuration documents,
27+
especially when the content needs to be passed through systems that expect URI-formatted data.
28+
29+
## Examples
30+
31+
### Example 1 - Convert a string to data URI
32+
33+
The configuration converts a basic string value with the `dataUri()` function.
34+
35+
```yaml
36+
# dataUri.example.1.dsc.config.yaml
37+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
38+
resources:
39+
- name: Convert 'Hello' to data URI
40+
type: Microsoft.DSC.Debug/Echo
41+
properties:
42+
output: "[dataUri('Hello')]"
43+
```
44+
45+
```bash
46+
dsc config get --file dataUri.example.1.dsc.config.yaml
47+
```
48+
49+
```yaml
50+
results:
51+
- name: Convert 'Hello' to data URI
52+
type: Microsoft.DSC.Debug/Echo
53+
result:
54+
actualState:
55+
output: data:text/plain;charset=utf8;base64,SGVsbG8=
56+
messages: []
57+
hadErrors: false
58+
```
59+
60+
### Example 2 - Convert a concatenated string to data URI
61+
62+
The configuration uses the [concat()][02] function inside the `dataUri()` function to combine
63+
strings before converting to a data URI.
64+
65+
```yaml
66+
# dataUri.example.2.dsc.config.yaml
67+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
68+
resources:
69+
- name: Convert concatenated string to data URI
70+
type: Microsoft.DSC.Debug/Echo
71+
properties:
72+
output: "[dataUri(concat('Hello', ', World!'))]"
73+
```
74+
75+
```bash
76+
dsc config get --file dataUri.example.2.dsc.config.yaml
77+
```
78+
79+
```yaml
80+
results:
81+
- name: Convert concatenated string to data URI
82+
type: Microsoft.DSC.Debug/Echo
83+
result:
84+
actualState:
85+
output: data:text/plain;charset=utf8;base64,SGVsbG8sIFdvcmxkIQ==
86+
messages: []
87+
hadErrors: false
88+
```
89+
90+
### Example 3 - Round-trip encoding and decoding
91+
92+
The configuration demonstrates encoding a string to a data URI and then decoding it back using the
93+
[dataUriToString()][03] function.
94+
95+
```yaml
96+
# dataUri.example.3.dsc.config.yaml
97+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
98+
resources:
99+
- name: Round-trip data URI conversion
100+
type: Microsoft.DSC.Debug/Echo
101+
properties:
102+
output: "[dataUriToString(dataUri('Configuration Data'))]"
103+
```
104+
105+
```bash
106+
dsc config get --file dataUri.example.3.dsc.config.yaml
107+
```
108+
109+
```yaml
110+
results:
111+
- name: Round-trip data URI conversion
112+
type: Microsoft.DSC.Debug/Echo
113+
result:
114+
actualState:
115+
output: Configuration Data
116+
messages: []
117+
hadErrors: false
118+
```
119+
120+
## Parameters
121+
122+
### stringToConvert
123+
124+
The `dataUri()` function expects a single string as input. The function converts the value into a
125+
data URI representation. If the value isn't a string, DSC raises an error when validating the
126+
configuration document.
127+
128+
```yaml
129+
Type: string
130+
Required: true
131+
MinimumCount: 1
132+
MaximumCount: 1
133+
```
134+
135+
## Output
136+
137+
The `dataUri()` function returns a data URI string in the format
138+
`data:text/plain;charset=utf8;base64,<encoded-content>` where `<encoded-content>` is the base64
139+
representation of the **stringToConvert** value.
140+
141+
```yaml
142+
Type: string
143+
```
144+
145+
<!-- Link reference definitions -->
146+
[01]: https://en.wikipedia.org/wiki/Data_URI_scheme
147+
[02]: concat.md
148+
[03]: dataUriToString.md

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

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
---
2+
description: Reference for the 'dataUriToString' DSC configuration document function
3+
ms.date: 12/20/2025
4+
ms.topic: reference
5+
title: dataUriToString
6+
---
7+
8+
# dataUriToString
9+
10+
## Synopsis
11+
12+
Converts a data URI formatted value to a string.
13+
14+
## Syntax
15+
16+
```Syntax
17+
dataUriToString(<dataUriToConvert>)
18+
```
19+
20+
## Description
21+
22+
The `dataUriToString()` function converts a [data URI][01] formatted value back to its original
23+
string representation. This function is the inverse of the [`dataUri()`][02] function and is useful
24+
for decoding data that was previously encoded as a data URI.
25+
26+
The function supports both base64-encoded data URIs (those containing `;base64` in the metadata)
27+
and URL-encoded data URIs. It automatically detects the encoding method and decodes accordingly.
28+
29+
## Examples
30+
31+
### Example 1 - Decode a base64-encoded data URI
32+
33+
The configuration decodes a data URI back to its original string value.
34+
35+
```yaml
36+
# dataUriToString.example.1.dsc.config.yaml
37+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
38+
resources:
39+
- name: Decode data URI
40+
type: Microsoft.DSC.Debug/Echo
41+
properties:
42+
output: "[dataUriToString('data:text/plain;charset=utf8;base64,SGVsbG8=')]"
43+
```
44+
45+
```bash
46+
dsc config get --file dataUriToString.example.1.dsc.config.yaml
47+
```
48+
49+
```yaml
50+
results:
51+
- name: Decode data URI
52+
type: Microsoft.DSC.Debug/Echo
53+
result:
54+
actualState:
55+
output: Hello
56+
messages: []
57+
hadErrors: false
58+
```
59+
60+
### Example 2 - Decode a data URI from parameter
61+
62+
This example shows decoding a data URI value passed through a parameter.
63+
64+
```yaml
65+
# dataUriToString.example.2.dsc.config.yaml
66+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
67+
parameters:
68+
dataFormattedString:
69+
type: string
70+
defaultValue: "data:;base64,SGVsbG8sIFdvcmxkIQ=="
71+
resources:
72+
- name: Decode data URI from parameter
73+
type: Microsoft.DSC.Debug/Echo
74+
properties:
75+
output: "[dataUriToString(parameters('dataFormattedString'))]"
76+
```
77+
78+
```bash
79+
dsc config get --file dataUriToString.example.2.dsc.config.yaml
80+
```
81+
82+
```yaml
83+
results:
84+
- name: Decode data URI from parameter
85+
type: Microsoft.DSC.Debug/Echo
86+
result:
87+
actualState:
88+
output: Hello, World!
89+
messages: []
90+
hadErrors: false
91+
```
92+
93+
### Example 3 - Round-trip encoding and decoding
94+
95+
The configuration demonstrates encoding a string to a data URI and then decoding it
96+
back using the [`dataUri()`][02] function inside the `dataUriToString()` function.
97+
98+
```yaml
99+
# dataUriToString.example.3.dsc.config.yaml
100+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
101+
resources:
102+
- name: Round-trip data URI conversion
103+
type: Microsoft.DSC.Debug/Echo
104+
properties:
105+
output: "[dataUriToString(dataUri('Configuration Data'))]"
106+
```
107+
108+
```bash
109+
dsc config get --file dataUriToString.example.3.dsc.config.yaml
110+
```
111+
112+
```yaml
113+
results:
114+
- name: Round-trip data URI conversion
115+
type: Microsoft.DSC.Debug/Echo
116+
result:
117+
actualState:
118+
output: Configuration Data
119+
messages: []
120+
hadErrors: false
121+
```
122+
123+
### Example 4 - Decode URL-encoded data URI
124+
125+
This example demonstrates decoding a data URI that uses URL encoding instead of base64.
126+
127+
```yaml
128+
# dataUriToString.example.4.dsc.config.yaml
129+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
130+
resources:
131+
- name: Decode URL-encoded data URI
132+
type: Microsoft.DSC.Debug/Echo
133+
properties:
134+
output: "[dataUriToString('data:text/plain,Hello%20World')]"
135+
```
136+
137+
```bash
138+
dsc config get --file dataUriToString.example.4.dsc.config.yaml
139+
```
140+
141+
```yaml
142+
results:
143+
- name: Decode URL-encoded data URI
144+
type: Microsoft.DSC.Debug/Echo
145+
result:
146+
actualState:
147+
output: Hello World
148+
messages: []
149+
hadErrors: false
150+
```
151+
152+
## Parameters
153+
154+
### dataUriToConvert
155+
156+
The `dataUriToString()` function expects a single string containing a valid data URI. The data URI
157+
must start with `data:` and contain a comma separating the metadata from the encoded data. If the
158+
metadata contains `;base64`, the data is decoded as base64; otherwise, it's decoded as URL-encoded.
159+
160+
```yaml
161+
Type: string
162+
Required: true
163+
MinimumCount: 1
164+
MaximumCount: 1
165+
```
166+
167+
## Output
168+
169+
The `dataUriToString()` function returns the decoded string representation of the
170+
**dataUriToConvert** parameter.
171+
172+
```yaml
173+
Type: string
174+
```
175+
176+
## Exceptions
177+
178+
The `dataUriToString()` function raises errors for the following conditions:
179+
180+
- **Invalid data URI format**: When the input string doesn't start with `data:` or doesn't contain
181+
a comma separator
182+
- **Invalid base64 encoding**: When the data portion contains invalid base64 characters (for
183+
base64-encoded data URIs)
184+
- **Invalid UTF-8**: When the decoded bytes do not form valid UTF-8 text
185+
186+
## Related functions
187+
188+
- [`dataUri()`][02] - Converts a value to a data URI
189+
- [`base64()`][03] - Encodes a string to base64 format
190+
- [`base64ToString()`][04] - Decodes a base64 string
191+
- [`parameters()`][05] - Retrieves parameter values
192+
193+
<!-- Link reference definitions -->
194+
[01]: https://en.wikipedia.org/wiki/Data_URI_scheme
195+
[02]: ./dataUri.md
196+
[03]: ./base64.md
197+
[04]: ./base64ToString.md
198+
[05]: ./parameters.md

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -671,6 +671,8 @@ The following list of functions are for manipulating strings:
671671
- [concat()][concat] - Return a combined string where the input strings are concatenated in the
672672
order they're specified.
673673
- [contains()][contains] - Check if an array contains a value or an object contains a key.
674+
- [dataUri()][dataUri] - Convert a value to a data URI.
675+
- [dataUriToString()][dataUriToString] - Convert a data URI formatted value to a string.
674676
- [empty()][empty] - Check if a value (string, array, or object) is empty.
675677
- [endsWith()][endsWith] - Check if a string ends with a specified suffix.
676678
- [first()][first] - Return the first element of an array or the first character of a string.
@@ -729,6 +731,8 @@ The following list of functions create or convert values of a given type:
729731
[copyIndex]: ./copyIndex.md
730732
[createArray]: ./createArray.md
731733
[createObject]: ./createObject.md
734+
[dataUri]: ./dataUri.md
735+
[dataUriToString]: ./dataUriToString.md
732736
[div]: ./div.md
733737
[empty]: ./empty.md
734738
[endsWith]: ./endsWith.md

0 commit comments

Comments
 (0)