Skip to content

Commit 55582bf

Browse files
Gijsreynmichaeltlombardi
Gijsreyn
and
michaeltlombardi
authored
docs: add Microsoft.DSC/Include reference documentation (#1649)
* docs: add `Microsoft.DSC/Include` reference documentation * Apply suggestions from review Co-authored-by: Mikey Lombardi (He/Him) <michael.t.lombardi@gmail.com> --------- Co-authored-by: Mikey Lombardi (He/Him) <michael.t.lombardi@gmail.com>
1 parent 23330fd commit 55582bf

3 files changed

Lines changed: 479 additions & 0 deletions

File tree

‎docs/reference/resources/Microsoft/DSC/Include/examples/include-a-configuration-file.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
description: >-
3+
Demonstrates how to include a configuration document from a file with the Microsoft.DSC/Include
4+
resource and pass it a parameters file.
5+
ms.date: 07/24/2026
6+
ms.topic: reference
7+
title: Include a configuration file
8+
---
9+
10+
This example demonstrates how to use the `Microsoft.DSC/Include` resource to compose a configuration
11+
from a separate configuration document on disk, and how to supply that document with a parameters
12+
file.
13+
14+
## Author the nested configuration document
15+
16+
First, author the configuration document that you want to include. This document defines a parameter
17+
named `osFamily` and uses it to check the operating system with the `Microsoft/OSInfo` resource.
18+
Save it as `osinfo.dsc.yaml`.
19+
20+
```yaml
21+
# osinfo.dsc.yaml
22+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
23+
parameters:
24+
osFamily:
25+
type: string
26+
defaultValue: Windows
27+
allowedValues:
28+
- Windows
29+
- Linux
30+
- macOS
31+
resources:
32+
- name: os
33+
type: Microsoft/OSInfo
34+
properties:
35+
family: "[parameters('osFamily')]"
36+
```
37+
38+
## Author the parameters file
39+
40+
Next, author the parameters file that supplies a value for the `osFamily` parameter. Save it next to
41+
the configuration document as `osinfo.parameters.yaml`.
42+
43+
```yaml
44+
# osinfo.parameters.yaml
45+
parameters:
46+
osFamily: macOS
47+
```
48+
49+
## Include the configuration and parameters
50+
51+
Finally, author the parent configuration document. The `Microsoft.DSC/Include` instance references
52+
the configuration document with the `configurationFile` property and the parameters file with the
53+
`parametersFile` property. Because the paths are relative, DSC resolves them against the parent
54+
document's directory.
55+
56+
```yaml
57+
# main.dsc.yaml
58+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
59+
resources:
60+
- name: os info
61+
type: Microsoft.DSC/Include
62+
properties:
63+
configurationFile: osinfo.dsc.yaml
64+
parametersFile: osinfo.parameters.yaml
65+
```
66+
67+
Invoke the [dsc config get][01] command against the parent document to retrieve the state of the
68+
included resources.
69+
70+
```powershell
71+
dsc config get --file ./main.dsc.yaml
72+
```
73+
74+
DSC resolves the included configuration, applies the `osFamily` value from the parameters file, and
75+
returns the result of the nested `Microsoft/OSInfo` instance. On a macOS machine, the output is
76+
similar to the following YAML:
77+
78+
```yaml
79+
results:
80+
- name: os info
81+
type: Microsoft.DSC/Include
82+
result:
83+
- name: os
84+
type: Microsoft/OSInfo
85+
result:
86+
actualState:
87+
$id: https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json
88+
family: macOS
89+
version: 15.5.0
90+
bitness: '64'
91+
architecture: arm64
92+
messages: []
93+
hadErrors: false
94+
```
95+
96+
> [!TIP]
97+
> To run the included configuration with its default parameter values instead, omit the
98+
> `parametersFile` property. The nested document then uses the `defaultValue` defined for each of
99+
> its parameters.
100+
101+
## See also
102+
103+
- [Microsoft.DSC/Include resource](../index.md)
104+
- [Include inline configuration content](./include-inline-configuration-content.md)
105+
- [Microsoft/OSInfo resource][02]
106+
107+
<!-- Link reference definitions -->
108+
[01]: ../../../../../cli/config/get.md
109+
[02]: ../../../../Microsoft/OSInfo/index.md

‎docs/reference/resources/Microsoft/DSC/Include/examples/include-inline-configuration-content.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
description: >-
3+
Demonstrates how to embed a configuration document and its parameters inline with the
4+
Microsoft.DSC/Include resource.
5+
ms.date: 07/24/2026
6+
ms.topic: reference
7+
title: Include inline configuration content
8+
---
9+
10+
This example demonstrates how to use the `Microsoft.DSC/Include` resource to embed a configuration
11+
document and its parameters directly in the parent document. Use inline content when you want to keep
12+
a self-contained configuration in a single file rather than referencing separate files on disk.
13+
14+
## Embed the configuration and parameters
15+
16+
Author the parent configuration document. Instead of referencing files, the `Microsoft.DSC/Include`
17+
instance defines the nested configuration with the `configurationContent` property and the parameter
18+
values with the `parametersContent` property. Both properties accept YAML or JSON as text. The
19+
following example uses YAML block scalars (`|`) to keep the nested documents readable.
20+
21+
```yaml
22+
# main.dsc.yaml
23+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
24+
resources:
25+
- name: os info
26+
type: Microsoft.DSC/Include
27+
properties:
28+
configurationContent: |
29+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
30+
parameters:
31+
osFamily:
32+
type: string
33+
defaultValue: Windows
34+
allowedValues:
35+
- Windows
36+
- Linux
37+
- macOS
38+
resources:
39+
- name: os
40+
type: Microsoft/OSInfo
41+
properties:
42+
family: "[parameters('osFamily')]"
43+
parametersContent: |
44+
parameters:
45+
osFamily: macOS
46+
```
47+
48+
Invoke the [dsc config get][01] command against the parent document to retrieve the state of the
49+
included resources.
50+
51+
```powershell
52+
dsc config get --file ./main.dsc.yaml
53+
```
54+
55+
DSC parses the inline configuration, applies the `osFamily` value from the inline parameters, and
56+
returns the result of the nested `Microsoft/OSInfo` instance. On a macOS machine, the output is
57+
similar to the following YAML:
58+
59+
```yaml
60+
results:
61+
- name: os info
62+
type: Microsoft.DSC/Include
63+
result:
64+
- name: os
65+
type: Microsoft/OSInfo
66+
result:
67+
actualState:
68+
$id: https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json
69+
family: macOS
70+
version: 15.5.0
71+
bitness: '64'
72+
architecture: arm64
73+
messages: []
74+
hadErrors: false
75+
```
76+
77+
> [!TIP]
78+
> Inline content is convenient for small configurations and for generating configurations
79+
> programmatically. For larger or reusable configurations, reference a file with the
80+
> `configurationFile` property instead. For that approach, see
81+
> [Include a configuration file](./include-a-configuration-file.md).
82+
83+
## See also
84+
85+
- [Microsoft.DSC/Include resource](../index.md)
86+
- [Include a configuration file](./include-a-configuration-file.md)
87+
- [Microsoft/OSInfo resource][02]
88+
89+
<!-- Link reference definitions -->
90+
[01]: ../../../../../cli/config/get.md
91+
[02]: ../../../../Microsoft/OSInfo/index.md

0 commit comments

Comments
 (0)