From 19f46f199fbac8c50d7482fcb666f04edd838117 Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Fri, 24 Jul 2026 11:40:59 +0200 Subject: [PATCH] docs: add `Microsoft.DSC/Include` reference documentation --- .../examples/include-a-configuration-file.md | 109 +++++++ .../include-inline-configuration-content.md | 91 ++++++ .../resources/Microsoft/DSC/Include/index.md | 279 ++++++++++++++++++ 3 files changed, 479 insertions(+) create mode 100644 docs/reference/resources/Microsoft/DSC/Include/examples/include-a-configuration-file.md create mode 100644 docs/reference/resources/Microsoft/DSC/Include/examples/include-inline-configuration-content.md diff --git a/docs/reference/resources/Microsoft/DSC/Include/examples/include-a-configuration-file.md b/docs/reference/resources/Microsoft/DSC/Include/examples/include-a-configuration-file.md new file mode 100644 index 000000000..dd4f75a4d --- /dev/null +++ b/docs/reference/resources/Microsoft/DSC/Include/examples/include-a-configuration-file.md @@ -0,0 +1,109 @@ +--- +description: >- + Demonstrates how to include a configuration document from a file with the Microsoft.DSC/Include + resource and pass it a parameters file. +ms.date: 07/24/2026 +ms.topic: reference +title: Include a configuration file +--- + +This example demonstrates how to use the `Microsoft.DSC/Include` resource to compose a configuration +from a separate configuration document on disk, and how to supply that document with a parameters +file. + +## Author the nested configuration document + +First, author the configuration document that you want to include. This document defines a parameter +named `osFamily` and uses it to check the operating system with the `Microsoft/OSInfo` resource. +Save it next to the parent document as `osinfo.dsc.yaml`. + +```yaml +# osinfo.dsc.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + osFamily: + type: string + defaultValue: Windows + allowedValues: + - Windows + - Linux + - macOS +resources: + - name: os + type: Microsoft/OSInfo + properties: + family: "[parameters('osFamily')]" +``` + +## Author the parameters file + +Next, author the parameters file that supplies a value for the `osFamily` parameter. Save it next to +the parent document as `osinfo.parameters.yaml`. + +```yaml +# osinfo.parameters.yaml +parameters: + osFamily: macOS +``` + +## Include the configuration and parameters + +Finally, author the parent configuration document. The `Microsoft.DSC/Include` instance references +the configuration document with the `configurationFile` property and the parameters file with the +`parametersFile` property. Because the paths are relative, DSC resolves them against the parent +document's directory. + +```yaml +# main.dsc.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: os info + type: Microsoft.DSC/Include + properties: + configurationFile: osinfo.dsc.yaml + parametersFile: osinfo.parameters.yaml +``` + +Invoke the [dsc config get][01] command against the parent document to retrieve the state of the +included resources. + +```powershell +dsc config get --file ./main.dsc.yaml +``` + +DSC resolves the included configuration, applies the `osFamily` value from the parameters file, and +returns the result of the nested `Microsoft/OSInfo` instance. On a macOS machine, the output is +similar to the following YAML: + +```yaml +results: +- name: os info + type: Microsoft.DSC/Include + result: + - name: os + type: Microsoft/OSInfo + result: + actualState: + $id: https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json + family: macOS + version: 15.5.0 + bitness: '64' + architecture: arm64 +messages: [] +hadErrors: false +``` + +> [!TIP] +> To run the included configuration with its default parameter values instead, omit the +> `parametersFile` property. The nested document then uses the `defaultValue` defined for each of +> its parameters. + +## See also + +- [Microsoft.DSC/Include resource](../index.md) +- [Include inline configuration content](./include-inline-configuration-content.md) +- [Microsoft/OSInfo resource][02] + + +[01]: ../../../../../cli/config/get.md +[02]: ../../../../Microsoft/OSInfo/index.md diff --git a/docs/reference/resources/Microsoft/DSC/Include/examples/include-inline-configuration-content.md b/docs/reference/resources/Microsoft/DSC/Include/examples/include-inline-configuration-content.md new file mode 100644 index 000000000..844be359e --- /dev/null +++ b/docs/reference/resources/Microsoft/DSC/Include/examples/include-inline-configuration-content.md @@ -0,0 +1,91 @@ +--- +description: >- + Demonstrates how to embed a configuration document and its parameters inline with the + Microsoft.DSC/Include resource. +ms.date: 07/24/2026 +ms.topic: reference +title: Include inline configuration content +--- + +This example demonstrates how to use the `Microsoft.DSC/Include` resource to embed a configuration +document and its parameters directly in the parent document. Use inline content when you want to keep +a self-contained configuration in a single file rather than referencing separate files on disk. + +## Embed the configuration and parameters + +Author the parent configuration document. Instead of referencing files, the `Microsoft.DSC/Include` +instance defines the nested configuration with the `configurationContent` property and the parameter +values with the `parametersContent` property. Both properties accept YAML or JSON as text. The +following example uses YAML block scalars (`|`) to keep the nested documents readable. + +```yaml +# main.dsc.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: os info + type: Microsoft.DSC/Include + properties: + configurationContent: | + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + parameters: + osFamily: + type: string + defaultValue: Windows + allowedValues: + - Windows + - Linux + - macOS + resources: + - name: os + type: Microsoft/OSInfo + properties: + family: "[parameters('osFamily')]" + parametersContent: | + parameters: + osFamily: macOS +``` + +Invoke the [dsc config get][01] command against the parent document to retrieve the state of the +included resources. + +```powershell +dsc config get --file ./main.dsc.yaml +``` + +DSC parses the inline configuration, applies the `osFamily` value from the inline parameters, and +returns the result of the nested `Microsoft/OSInfo` instance. On a macOS machine, the output is +similar to the following YAML: + +```yaml +results: +- name: os info + type: Microsoft.DSC/Include + result: + - name: os + type: Microsoft/OSInfo + result: + actualState: + $id: https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json + family: macOS + version: 15.5.0 + bitness: '64' + architecture: arm64 +messages: [] +hadErrors: false +``` + +> [!TIP] +> Inline content is convenient for small configurations and for generating configurations +> programmatically. For larger or reusable configurations, reference a file with the +> `configurationFile` property instead. For that approach, see +> [Include a configuration file](./include-a-configuration-file.md). + +## See also + +- [Microsoft.DSC/Include resource](../index.md) +- [Include a configuration file](./include-a-configuration-file.md) +- [Microsoft/OSInfo resource][02] + + +[01]: ../../../../../cli/config/get.md +[02]: ../../../../Microsoft/OSInfo/index.md diff --git a/docs/reference/resources/Microsoft/DSC/Include/index.md b/docs/reference/resources/Microsoft/DSC/Include/index.md index e69de29bb..22dcb2ae1 100644 --- a/docs/reference/resources/Microsoft/DSC/Include/index.md +++ b/docs/reference/resources/Microsoft/DSC/Include/index.md @@ -0,0 +1,279 @@ +--- +description: Microsoft.DSC/Include resource reference documentation +ms.date: 07/24/2026 +ms.topic: reference +title: Microsoft.DSC/Include +--- + +# Microsoft.DSC/Include + +## Synopsis + +Includes a nested configuration document, with optional parameters, into the current configuration. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : importer +Tags : [Windows, Linux, MacOS] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.DSC/Include + properties: + # Specify the nested configuration with one of the following properties: + configurationFile: string # Path to a configuration document file. + configurationContent: string # Inline configuration document as text. + # Optionally specify parameters with one of the following properties: + parametersFile: string # Path to a parameters file. + parametersContent: string # Inline parameters as text. +``` + +## Description + +The `Microsoft.DSC/Include` resource lets you compose a configuration from more than one +configuration document. Instead of defining every resource instance in a single document, you can +author smaller documents and reference them from a parent document. When DSC processes an instance +of the `Microsoft.DSC/Include` resource, it resolves the nested configuration document, applies any +parameters you specify, and runs the operation against the nested resources as a group. + +Use the `Microsoft.DSC/Include` resource when you want to: + +- Reuse a common configuration document across multiple parent configurations. +- Split a large configuration into smaller, focused documents that are easier to maintain. +- Apply the same configuration with different parameter values in different contexts. + +You define the nested configuration in one of two mutually exclusive ways: + +- Reference a document on disk with the [configurationFile](#configurationfile) property. +- Embed the document inline as text with the [configurationContent](#configurationcontent) property. + +Similarly, you can optionally pass parameters to the nested document in one of two mutually +exclusive ways: + +- Reference a parameters file on disk with the [parametersFile](#parametersfile) property. +- Embed the parameters inline as text with the [parametersContent](#parameterscontent) property. + +Both the configuration and the parameters can be authored as either YAML or JSON. DSC detects the +format when it parses the content. + +> [!NOTE] +> This resource is installed with DSC itself on any systems. +> +> You can update this resource by updating DSC. When you update DSC, the updated version of this +> resource is automatically available. + +### Path resolution and security + +When you specify a relative path for the [configurationFile](#configurationfile) or +[parametersFile](#parametersfile) properties, DSC resolves the path against the directory of the +parent configuration document. DSC uses the `DSC_CONFIG_ROOT` environment variable to determine +that directory. When you invoke DSC with configuration content instead of a file on disk, DSC +resolves relative paths against the current working directory. + +For security, relative paths **can't** reference a parent directory. A path that contains a `..` +segment raises an error. To include a configuration outside of the parent document's directory, use +an absolute path or construct the path with a configuration function like [path()][05] or +[systemRoot()][06]. + +### Nested and repeated includes + +An included configuration document can itself contain instances of the `Microsoft.DSC/Include` +resource. DSC resolves each level of nesting in turn, so you can build a hierarchy of configuration +documents. You can also define more than one `Microsoft.DSC/Include` instance in the same document +to compose several configurations together. + +## Capabilities + +The resource has the following capabilities: + +- `get` - You can use the resource to retrieve the actual state of the nested resource instances. +- `set` - You can use the resource to enforce the desired state for the nested resource instances. +- `test` - You can use the resource to check whether the nested resource instances are in the + desired state. + +Because this resource is an [importer resource][03], it doesn't manage state directly. Instead, it +resolves the nested configuration document and DSC invokes the requested operation against the +resources defined in that document. + +For more information about resource capabilities, see [DSC resource capabilities][01]. + +## Examples + +1. [Include a configuration file][07] - Shows how to reference a configuration document and pass it + a parameters file. +1. [Include inline configuration content][08] - Shows how to embed a configuration document and its + parameters directly in the parent document. + +## Properties + +The following list describes the properties for the resource. + +- **Configuration properties:** You must define exactly one of + the following properties to specify the nested configuration document. An instance that defines + neither property, or both, is invalid. + + - [configurationFile](#configurationfile) - The path to a configuration document file. + - [configurationContent](#configurationcontent) - An inline configuration document as text. + +- **Parameter properties:** You can optionally define one of the + following properties to pass parameters to the nested configuration document. An instance that + defines both properties is invalid. + + - [parametersFile](#parametersfile) - The path to a parameters file. + - [parametersContent](#parameterscontent) - Inline parameters as text. + +### configurationFile + +
Expand for configurationFile property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the path to the configuration document file to include. The file can be authored as YAML or +JSON. When you specify a relative path, DSC resolves it against the parent configuration document's +directory and the path can't reference a parent directory. For more information, see +[Path resolution and security](#path-resolution-and-security). + +Define either this property or [configurationContent](#configurationcontent), but not both. + +### configurationContent + +
Expand for configurationContent property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the configuration document to include as inline text. The content can be authored as YAML or +JSON. Use this property when you want to keep the nested configuration in the same document rather +than referencing a separate file. + +Define either this property or [configurationFile](#configurationfile), but not both. + +### parametersFile + +
Expand for parametersFile property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the path to a parameters file that supplies values for the parameters defined in the nested +configuration document. The file can be authored as YAML or JSON. When you specify a relative path, +DSC resolves it against the parent configuration document's directory and the path can't reference a +parent directory. For more information, see +[Path resolution and security](#path-resolution-and-security). + +Define either this property or [parametersContent](#parameterscontent), but not both. This property +is optional. When you don't specify parameters, the nested configuration uses the default value for +each of its parameters. + +### parametersContent + +
Expand for parametersContent property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the parameters for the nested configuration document as inline text. The content can be +authored as YAML or JSON. Use this property when you want to keep the parameter values in the same +document rather than referencing a separate file. + +Define either this property or [parametersFile](#parametersfile), but not both. This property is +optional. When you don't specify parameters, the nested configuration uses the default value for +each of its parameters. + +## Instance validating schema + +The following snippet contains the JSON Schema that validates an instance of the resource. The +validating schema only includes schema keywords that affect how the instance is validated. All +non validating keywords are omitted. + +```json +{ + "type": "object", + "properties": { + "configurationFile": { + "title": "Configuration file", + "description": "The path to the configuration document file to include.", + "type": "string" + }, + "configurationContent": { + "title": "Configuration content", + "description": "The configuration document to include as inline text.", + "type": "string" + }, + "parametersFile": { + "title": "Parameters file", + "description": "The path to a parameters file for the included configuration.", + "type": "string" + }, + "parametersContent": { + "title": "Parameters content", + "description": "The parameters for the included configuration as inline text.", + "type": "string" + } + }, + "oneOf": [ + { "required": ["configurationFile"] }, + { "required": ["configurationContent"] } + ], + "not": { + "required": ["parametersFile", "parametersContent"] + }, + "additionalProperties": false +} +``` + +## See also + +- [Microsoft.DSC/Group resource][09] +- [Microsoft.DSC/Assertion resource][10] +- [Microsoft/OSInfo resource][11] +- [DSC configuration documents][04] +- [DSC resource capabilities][01] + + +[01]: ../../../../../concepts/resources/capabilities.md +[03]: ../../../../../concepts/resources/kinds.md +[04]: ../../../../../concepts/configuration-documents/overview.md +[05]: ../../../../schemas/config/functions/path.md +[06]: ../../../../schemas/config/functions/systemRoot.md +[07]: ./examples/include-a-configuration-file.md +[08]: ./examples/include-inline-configuration-content.md +[09]: ../Group/index.md +[10]: ../Assertion/index.md +[11]: ../../../Microsoft/OSInfo/index.md