(DOCS) Document parameters implementation

This change adds documentation to the CLI and schema reference
for the parameters support  implementation in #291 and #294. It
also updates the changelog with the relevant information.

CHANGELOG.md

@@ -2,7 +2,7 @@
 title: "Desired State Configuration changelog"
 description: >-
   A log of the changes for releases of DSCv3.
-ms.date: 01/17/2024
+ms.date: 02/05/2024
 ---
 
 # Changelog
@@ -24,6 +24,24 @@ changes since the last release, see the [diff on GitHub][unreleased].
 <!-- Unreleased comparison link -->
 [unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...main
 
+### Added
+
+- Implemented support for referencing parameters in a configuration with the [parameters()][32]
+  configuration function. This enables you to take advantage of parameterized configurations. Until
+  this release, you could define but not reference parameters.
+
+  Now, you can use the [--parameters][33] and [--parameters-file][34] options with the
+  [dsc config][35] commands to pass values for any parameter defined in the configuration document.
+
+  <details><summary>Related work items</summary>
+
+  - Issues: [#49][#49]
+  - PRs:
+    - [#291][#291]
+    - [#294][#294]
+
+  </details>
+
 <!-- Add entries between releases under the appropriate section heading here  -->
 
 ## [v3.0.0-alpha.4][release-v3.0.0-alpha.4] - 2023-11-14
@@ -472,6 +490,12 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
 [30]: docs/reference/schemas/config/functions/concat.md
 [31]: docs/reference/schemas/config/functions/resourceId.md
 
+<!-- alpha.5 links -->
+[32]: docs/reference/schemas/config/functions/parameters.md
+[33]: docs/reference/cli/config/command.md#-p---parameters
+[34]: docs/reference/cli/config/command.md#-f---parameters_file
+[35]: docs/reference/cli/config/command.md
+
 <!-- Issue and PR links -->
 [#107]: https://github.com/PowerShell/DSC/issues/107
 [#121]: https://github.com/PowerShell/DSC/issues/121
@@ -510,7 +534,10 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
 [#241]: https://github.com/PowerShell/DSC/issues/241
 [#248]: https://github.com/PowerShell/DSC/issues/248
 [#252]: https://github.com/PowerShell/DSC/issues/252
+[#291]: https://github.com/PowerShell/DSC/issues/291
+[#294]: https://github.com/PowerShell/DSC/issues/294
 [#45]:  https://github.com/PowerShell/DSC/issues/45
+[#49]:  https://github.com/PowerShell/DSC/issues/49
 [#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/cli/config/command.md

@@ -1,6 +1,6 @@
 ---
 description: Command line reference for the 'dsc config' command
-ms.date:     09/06/2023
+ms.date:     02/05/2024
 ms.topic:    reference
 title:       dsc config
 ---
@@ -62,6 +62,42 @@ information. For example, `dsc config --help` or `dsc config set --help`.
 
 ## Options
 
+### -f, --parameters_file
+
+Specifies the path to a data file containing the parameters to pass to the configuration as JSON or
+YAML. When you specify this option, DSC interprets the keys in the data file as parameters and uses
+the specified values. The values in the data file override any defaults defined in the
+configuration itself.
+
+The data file must contain an object with the `parameters` key. The value of the `parameters` key
+must be an object where each key is the name of a defined parameter and each value is a valid value
+for that parameter.
+
+This option can't be used with the `--parameters` option. Choose whether to pass the parameters as
+a data string with the `--parameters` option or in a data file with the `--parameters_file` option.
+
+For more information about defining parameters in a configuration document, see
+[DSC Configuration document parameter schema][06]. For more information about using parameters in
+configuration document, see the [parameters function reference][07].
+
+### -p, --parameters
+
+Specifies the parameters to pass to the configuration as a JSON or YAML string. When you specify
+this option, DSC interprets the keys in the data string as parameters and uses the specified
+values. The values in the data string override any defaults defined in the configuration itself.
+
+The data string must contain an object with the `parameters` key. The value of the `parameters` key
+must be an object where each key is the name of a defined parameter and each value is a valid value
+for that parameter.
+
+This option can't be used with the `--parameters_file` option. Choose whether to pass the
+parameters as a data string with the `--parameters` option or in a data file with the
+`--parameters_file` option.
+
+For more information about defining parameters in a configuration document, see
+[DSC Configuration document parameter schema][06]. For more information about using parameters in
+configuration document, see the [parameters function reference][07].
+
 ### -h, --help
 
 Displays the help for the current command or subcommand. When you specify this option, the
@@ -77,3 +113,5 @@ Mandatory: false
 [03]: get.md
 [04]: set.md
 [05]: test.md
+[06]: ../../schemas/config/parameter.md
+[07]: ../../schemas/config/functions/parameters.md

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

@@ -0,0 +1,112 @@
+---
+description: Reference for the 'parameters' DSC configuration document function
+ms.date:     02/05/2024
+ms.topic:    reference
+title:       parameters
+---
+
+# parameters
+
+## Synopsis
+
+Returns the value of a configuration parameter.
+
+## Syntax
+
+```Syntax
+parameters('<name>')
+```
+
+## Description
+
+The `parameters()` function returns the value of a specific parameter. You must pass the name of
+a valid parameter. When using this function for a resource instance, DSC validates the instance
+properties after this function runs and before calling the resource for the current operation. If
+the referenced parameter value is invalid for the property, DSC raises a validation error.
+
+For more information about defining parameters in a configuration document, see
+[DSC Configuration document parameter schema][01].
+
+## Examples
+
+### Example 1 - Use a parameter as a resource instance property value
+
+The configuration uses the `parameters()` function to echo the value of the `message` parameter.
+
+```yaml
+# parameters.example.1.dsc.config.yaml
+$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
+parameters:
+  message:
+    type:         string
+    defaultValue: Hello, world!
+resources:
+  - name: Echo message parameter
+    type: Test/Echo
+    properties:
+      text: "[parameters('message')]"
+```
+
+First, get the current state of the configuration without overriding the parameters with the
+[--parameters][02] or [`--parameters_file`][03] options. The output shows the default value for the
+`message` parameter.
+
+```bash
+config_file=parameters.example.1.dsc.config.yaml
+cat $config_file | dsc config get
+```
+
+```yaml
+results:
+- name: Echo message parameter
+  type: Test/Echo
+  result:
+    actualState:
+      text: Hello, world!
+messages: []
+hadErrors: false
+```
+
+Next, override the `message` parameter with the `--parameters` option.
+
+```bash
+params='{"parameters": {"message": "Hi, override."}}'
+cat $config_file | dsc config --parameters $params get
+```
+
+```yaml
+results:
+- name: Echo message parameter
+  type: Test/Echo
+  result:
+    actualState:
+      text: Hi, override.
+messages: []
+hadErrors: false
+```
+
+## Parameters
+
+### name
+
+The name of the parameter to return.
+
+```yaml
+Type:         string
+Required:     true
+MinimumCount: 1
+MaximumCount: 1
+```
+
+## Output
+
+The output of the function is the value of the specified parameter.
+
+```yaml
+Type: [string, int, bool, object, array]
+```
+
+<!-- Link reference definitions -->
+[01]: ../parameter.md
+[02]: ../../../cli/config/command.md#-p---parameters
+[03]: ../../../cli/config/command.md#-f---parameters_file

docs/reference/schemas/config/parameter.md

@@ -32,6 +32,8 @@ property of the configuration document. The value is an object that defines the
 Every parameter defines its data type. Parameters may also define a default value, validation
 checks, a description of their purpose, and arbitrary metadata.
 
+To reference parameters in resource instances, use the [parameters() configuration function][02].
+
 ## Required Properties
 
 - [type](#type)
@@ -72,7 +74,7 @@ independent logging or recording that isn't handled by DSC, the value may be sto
 Use secure strings for passwords and secrets.
 
 For more information about data types, see
-[DSC configuration parameter data type schema reference][02].
+[DSC configuration parameter data type schema reference][03].
 
 ```yaml
 Type:        string
@@ -172,4 +174,5 @@ Required: false
 ```
 
 [01]: resource.md
-[02]: ../definitions/parameters/dataTypes.md
+[02]: ./functions/parameters.md
+[03]: ../definitions/parameters/dataTypes.md