Skip to content

Commit 57bdcaa

Browse files
michaeltlombardimichaeltlombardi
committed
(DOCS) Document parameters implementation
This change adds documentation to the CLI and schema reference for the parameters support implementation in PowerShell#291 and PowerShell#294. It also updates the changelog with the relevant information.
1 parent 1fb90f6 commit 57bdcaa

File tree

4 files changed

+184
-4
lines changed

4 files changed

+184
-4
lines changed

‎CHANGELOG.md

+28-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: "Desired State Configuration changelog"
33
description: >-
44
A log of the changes for releases of DSCv3.
5-
ms.date: 01/17/2024
5+
ms.date: 02/05/2024
66
---
77

88
# Changelog
@@ -24,6 +24,24 @@ changes since the last release, see the [diff on GitHub][unreleased].
2424
<!-- Unreleased comparison link -->
2525
[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...main
2626

27+
### Added
28+
29+
- Implemented support for referencing parameters in a configuration with the [parameters()][32]
30+
configuration function. This enables you to take advantage of parameterized configurations. Until
31+
this release, you could define but not reference parameters.
32+
33+
Now, you can use the [--parameters][33] and [--parameters-file][34] options with the
34+
[dsc config][35] commands to pass values for any parameter defined in the configuration document.
35+
36+
<details><summary>Related work items</summary>
37+
38+
- Issues: [#49][#49]
39+
- PRs:
40+
- [#291][#291]
41+
- [#294][#294]
42+
43+
</details>
44+
2745
<!-- Add entries between releases under the appropriate section heading here -->
2846

2947
## [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
472490
[30]: docs/reference/schemas/config/functions/concat.md
473491
[31]: docs/reference/schemas/config/functions/resourceId.md
474492

493+
<!-- alpha.5 links -->
494+
[32]: docs/reference/schemas/config/functions/parameters.md
495+
[33]: docs/reference/cli/config/command.md#-p---parameters
496+
[34]: docs/reference/cli/config/command.md#-f---parameters_file
497+
[35]: docs/reference/cli/config/command.md
498+
475499
<!-- Issue and PR links -->
476500
[#107]: https://github.com/PowerShell/DSC/issues/107
477501
[#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
510534
[#241]: https://github.com/PowerShell/DSC/issues/241
511535
[#248]: https://github.com/PowerShell/DSC/issues/248
512536
[#252]: https://github.com/PowerShell/DSC/issues/252
537+
[#291]: https://github.com/PowerShell/DSC/issues/291
538+
[#294]: https://github.com/PowerShell/DSC/issues/294
513539
[#45]: https://github.com/PowerShell/DSC/issues/45
540+
[#49]: https://github.com/PowerShell/DSC/issues/49
514541
[#57]: https://github.com/PowerShell/DSC/issues/57
515542
[#73]: https://github.com/PowerShell/DSC/issues/73
516543
[#98]: https://github.com/PowerShell/DSC/issues/98

‎docs/reference/cli/config/command.md

+39-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: Command line reference for the 'dsc config' command
3-
ms.date: 09/06/2023
3+
ms.date: 02/05/2024
44
ms.topic: reference
55
title: dsc config
66
---
@@ -62,6 +62,42 @@ information. For example, `dsc config --help` or `dsc config set --help`.
6262

6363
## Options
6464

65+
### -f, --parameters_file
66+
67+
Specifies the path to a data file containing the parameters to pass to the configuration as JSON or
68+
YAML. When you specify this option, DSC interprets the keys in the data file as parameters and uses
69+
the specified values. The values in the data file override any defaults defined in the
70+
configuration itself.
71+
72+
The data file must contain an object with the `parameters` key. The value of the `parameters` key
73+
must be an object where each key is the name of a defined parameter and each value is a valid value
74+
for that parameter.
75+
76+
This option can't be used with the `--parameters` option. Choose whether to pass the parameters as
77+
a data string with the `--parameters` option or in a data file with the `--parameters_file` option.
78+
79+
For more information about defining parameters in a configuration document, see
80+
[DSC Configuration document parameter schema][06]. For more information about using parameters in
81+
configuration document, see the [parameters function reference][07].
82+
83+
### -p, --parameters
84+
85+
Specifies the parameters to pass to the configuration as a JSON or YAML string. When you specify
86+
this option, DSC interprets the keys in the data string as parameters and uses the specified
87+
values. The values in the data string override any defaults defined in the configuration itself.
88+
89+
The data string must contain an object with the `parameters` key. The value of the `parameters` key
90+
must be an object where each key is the name of a defined parameter and each value is a valid value
91+
for that parameter.
92+
93+
This option can't be used with the `--parameters_file` option. Choose whether to pass the
94+
parameters as a data string with the `--parameters` option or in a data file with the
95+
`--parameters_file` option.
96+
97+
For more information about defining parameters in a configuration document, see
98+
[DSC Configuration document parameter schema][06]. For more information about using parameters in
99+
configuration document, see the [parameters function reference][07].
100+
65101
### -h, --help
66102

67103
Displays the help for the current command or subcommand. When you specify this option, the
@@ -77,3 +113,5 @@ Mandatory: false
77113
[03]: get.md
78114
[04]: set.md
79115
[05]: test.md
116+
[06]: ../../schemas/config/parameter.md
117+
[07]: ../../schemas/config/functions/parameters.md

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

+112
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
description: Reference for the 'parameters' DSC configuration document function
3+
ms.date: 02/05/2024
4+
ms.topic: reference
5+
title: parameters
6+
---
7+
8+
# parameters
9+
10+
## Synopsis
11+
12+
Returns the value of a configuration parameter.
13+
14+
## Syntax
15+
16+
```Syntax
17+
parameters('<name>')
18+
```
19+
20+
## Description
21+
22+
The `parameters()` function returns the value of a specific parameter. You must pass the name of
23+
a valid parameter. When using this function for a resource instance, DSC validates the instance
24+
properties after this function runs and before calling the resource for the current operation. If
25+
the referenced parameter value is invalid for the property, DSC raises a validation error.
26+
27+
For more information about defining parameters in a configuration document, see
28+
[DSC Configuration document parameter schema][01].
29+
30+
## Examples
31+
32+
### Example 1 - Use a parameter as a resource instance property value
33+
34+
The configuration uses the `parameters()` function to echo the value of the `message` parameter.
35+
36+
```yaml
37+
# parameters.example.1.dsc.config.yaml
38+
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
39+
parameters:
40+
message:
41+
type: string
42+
defaultValue: Hello, world!
43+
resources:
44+
- name: Echo message parameter
45+
type: Test/Echo
46+
properties:
47+
text: "[parameters('message')]"
48+
```
49+
50+
First, get the current state of the configuration without overriding the parameters with the
51+
[--parameters][02] or [`--parameters_file`][03] options. The output shows the default value for the
52+
`message` parameter.
53+
54+
```bash
55+
config_file=parameters.example.1.dsc.config.yaml
56+
cat $config_file | dsc config get
57+
```
58+
59+
```yaml
60+
results:
61+
- name: Echo message parameter
62+
type: Test/Echo
63+
result:
64+
actualState:
65+
text: Hello, world!
66+
messages: []
67+
hadErrors: false
68+
```
69+
70+
Next, override the `message` parameter with the `--parameters` option.
71+
72+
```bash
73+
params='{"parameters": {"message": "Hi, override."}}'
74+
cat $config_file | dsc config --parameters $params get
75+
```
76+
77+
```yaml
78+
results:
79+
- name: Echo message parameter
80+
type: Test/Echo
81+
result:
82+
actualState:
83+
text: Hi, override.
84+
messages: []
85+
hadErrors: false
86+
```
87+
88+
## Parameters
89+
90+
### name
91+
92+
The name of the parameter to return.
93+
94+
```yaml
95+
Type: string
96+
Required: true
97+
MinimumCount: 1
98+
MaximumCount: 1
99+
```
100+
101+
## Output
102+
103+
The output of the function is the value of the specified parameter.
104+
105+
```yaml
106+
Type: [string, int, bool, object, array]
107+
```
108+
109+
<!-- Link reference definitions -->
110+
[01]: ../parameter.md
111+
[02]: ../../../cli/config/command.md#-p---parameters
112+
[03]: ../../../cli/config/command.md#-f---parameters_file

‎docs/reference/schemas/config/parameter.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ property of the configuration document. The value is an object that defines the
3232
Every parameter defines its data type. Parameters may also define a default value, validation
3333
checks, a description of their purpose, and arbitrary metadata.
3434

35+
To reference parameters in resource instances, use the [parameters() configuration function][02].
36+
3537
## Required Properties
3638

3739
- [type](#type)
@@ -72,7 +74,7 @@ independent logging or recording that isn't handled by DSC, the value may be sto
7274
Use secure strings for passwords and secrets.
7375

7476
For more information about data types, see
75-
[DSC configuration parameter data type schema reference][02].
77+
[DSC configuration parameter data type schema reference][03].
7678

7779
```yaml
7880
Type: string
@@ -172,4 +174,5 @@ Required: false
172174
```
173175

174176
[01]: resource.md
175-
[02]: ../definitions/parameters/dataTypes.md
177+
[02]: ./functions/parameters.md
178+
[03]: ../definitions/parameters/dataTypes.md

0 commit comments

Comments
 (0)