From 73ef6ac60a3bcc7234d0a321b977b4fdf5c3bb99 Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Fri, 4 Sep 2026 04:44:07 +0200 Subject: [PATCH] docs: Update configuration document schema reference --- docs/reference/schemas/config/document.md | 318 ++++++++++++++++++--- docs/reference/schemas/config/metadata.md | 37 ++- docs/reference/schemas/config/parameter.md | 8 +- docs/reference/schemas/config/resource.md | 270 +++++++++++++---- 4 files changed, 527 insertions(+), 106 deletions(-) diff --git a/docs/reference/schemas/config/document.md b/docs/reference/schemas/config/document.md index 622054720..4ceb997bf 100644 --- a/docs/reference/schemas/config/document.md +++ b/docs/reference/schemas/config/document.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a Desired State Configuration document. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Configuration document schema reference --- @@ -93,7 +93,7 @@ For every version of the schema, there are three valid URLs: it includes additional definitions that provide contextual help and snippets that the others don't include. - This schema uses keywords that are only recognized by Visual Studio Code. While DSC can still validate the + This schema uses keywords that are only recognized by VS Code. While DSC can still validate the document when it uses this schema, other tools may error or behave in unexpected ways. ```yaml @@ -104,9 +104,33 @@ ValidValues: [ https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/config/document.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/config/document.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/config/document.vscode.json @@ -125,9 +149,33 @@ ValidValues: [ https://aka.ms/dsc/schemas/v3/config/document.json https://aka.ms/dsc/schemas/v3/bundled/config/document.json https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.2/config/document.json + https://aka.ms/dsc/schemas/v3.2/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.2/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.2.3/config/document.json + https://aka.ms/dsc/schemas/v3.2.3/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.2.3/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.2.2/config/document.json + https://aka.ms/dsc/schemas/v3.2.2/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.2.2/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.2.1/config/document.json + https://aka.ms/dsc/schemas/v3.2.1/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.2.1/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.2.0/config/document.json + https://aka.ms/dsc/schemas/v3.2.0/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.2.0/bundled/config/document.vscode.json https://aka.ms/dsc/schemas/v3.1/config/document.json https://aka.ms/dsc/schemas/v3.1/bundled/config/document.json https://aka.ms/dsc/schemas/v3.1/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.1.3/config/document.json + https://aka.ms/dsc/schemas/v3.1.3/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.1.3/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.1.2/config/document.json + https://aka.ms/dsc/schemas/v3.1.2/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.1.2/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.1.1/config/document.json + https://aka.ms/dsc/schemas/v3.1.1/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.1.1/bundled/config/document.vscode.json https://aka.ms/dsc/schemas/v3.1.0/config/document.json https://aka.ms/dsc/schemas/v3.1.0/bundled/config/document.json https://aka.ms/dsc/schemas/v3.1.0/bundled/config/document.vscode.json @@ -146,11 +194,208 @@ ValidValues: [ ] ``` +### contentVersion + +The `contentVersion` property defines a version string for the configuration document. You can use +this property to track revisions of the document. DSC doesn't validate or use this value when +processing a configuration document. The document that the `dsc config export` command returns +always defines this property as `1.0.0`. + +```yaml +Type: string +Required: false +``` + +### directives + +The `directives` property defines how DSC processes the configuration document as a whole. Every +directive is optional. + +```yaml +Type: object +Required: false +``` + +You can define the following directives for a configuration document: + +#### resourceDiscovery + +The `resourceDiscovery` directive controls when DSC raises an error for a resource that it can't +find. When you don't define this directive or set it to `preDeployment`, DSC discovers resources +and extensions before invoking any resource instance and raises an error if any instance in the +document uses a resource that DSC didn't discover. + +Set this directive to `duringDeployment` to defer this check until DSC processes each instance. +This is useful when the configuration document itself installs a resource that a later instance +depends on. With this setting, DSC performs discovery again when it processes an instance whose +resource wasn't initially discovered and only raises an error if the resource isn't available at +that time. + +```yaml +Type: string +Required: false +Default: preDeployment +ValidValues: [preDeployment, duringDeployment] +``` + +#### securityContext + +The `securityContext` directive defines the security context the configuration document requires. +Before invoking any resource instances, DSC validates that it's running in the required security +context and raises an error if it isn't: + +- `current` - DSC can process the document in any security context. This is the default. +- `elevated` - DSC must be running as `root` (non-Windows) or in an elevated session with + Administrator privileges (Windows). +- `restricted` - DSC must be running as a normal user or account in a non-elevated session. + +This directive replaces the deprecated `Microsoft.DSC.securityContext` property in the document's +[metadata][02]. If you define both, the values must match or DSC raises an error. A resource +instance can override this directive with its own `directives.securityContext` setting. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + +#### version + +The `version` directive defines a semantic version requirement for DSC itself. When you define this +directive, DSC compares its own version to the requirement before invoking any resource instances +and raises an error if its version doesn't satisfy the requirement. This enables you to prevent a +configuration document from being processed by an incompatible version of DSC. + +The value must be one or more comparators separated by commas. Each comparator is an operator +(`=`, `>`, `>=`, `<`, `<=`, `^`, or `~`) followed by a version, like `>=3.2.0, <4.0.0`. Build +metadata isn't allowed in the version. The syntax is the same as for the `requireVersion` property +of a resource instance. For more information, see [requireVersion][03]. + +```yaml +Type: string +Required: false +``` + +### executionInformation + +The `executionInformation` property describes the DSC operation that produced a configuration +document. DSC adds this property to the document returned by the `dsc config export` command. The +schema accepts this property in any configuration document, but DSC ignores it when it processes +the document. + +The value is an object with the same properties as the [Microsoft.DSC metadata][04] object that DSC +returns in command output, plus an optional `whatIf` property that describes any what-if +operations DSC performed. + +```yaml +Type: object +Required: false +``` + +### functions + +The `functions` property defines user-defined functions that you can call in configuration +expressions anywhere in the document. Each item in the list defines a namespace and the functions +that belong to it: + +- `namespace` - Required. The name that groups the functions. You call a user-defined function as + `.()`. +- `members` - Required. An object that maps each function name to its definition. Each definition + is an object with the following properties: + + - `parameters` - Optional. A list of parameters for the function. Each parameter is an object + that defines the `name` and `type` of the parameter. The `type` must be one of the + [parameter data types][05]. When you call the function, DSC raises an error if the number of + arguments or their types don't match the parameters. + - `output` - Required. An object that defines the `type` of the value the function returns and + the `value` as a string. DSC evaluates the `value` as a configuration expression and raises an + error if the result doesn't match the declared `type`. + +In the `value` expression, use the [parameters()][06] function to access the function's own +parameters. User-defined functions can't access the document's parameters or variables, can't use +the `reference()` function, and can't call other user-defined functions. + +For example, this document defines the `contoso.greet()` function and calls it in a resource +instance: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +functions: + - namespace: contoso + members: + greet: + parameters: + - name: name + type: string + output: + type: string + value: "[format('Hello, {0}!', parameters('name'))]" +resources: + - name: Greeting + type: Microsoft.DSC.Debug/Echo + properties: + output: "[contoso.greet('World')]" +``` + +```yaml +Type: array +Required: false +ItemsType: object +``` + ### metadata -The `metadata` property defines a set of key-value pairs as annotations for the configuration. DSC -doesn't validate the metadata. A configuration can include any arbitrary information in this -property. +The `metadata` property defines a set of key-value pairs as annotations for the configuration. +Except for the `Microsoft.DSC` property, DSC doesn't validate the metadata. A configuration can +include any arbitrary information in this property. + +The `Microsoft.DSC` property is reserved for DSC. For more information, see +[DSC Configuration document metadata schema][02]. + +```yaml +Type: object +Required: false +``` + +### outputs + +The `outputs` property defines values that DSC evaluates after it processes every resource instance +in the document and returns in the `outputs` property of the command output. Each output is defined +as a key-value pair. The key is the name of the output. The value is an object with the following +properties: + +- `type` - Required. The [data type][05] of the output value. DSC raises an error if the evaluated + value doesn't match this type. DSC doesn't return outputs with the `secureString` or + `secureObject` types. Instead, it raises a warning and skips them. +- `value` - Required. A string that DSC evaluates as a configuration expression. Use this property + to return data from resource results, parameters, variables, and functions, like + `"[reference(resourceId('Microsoft.DSC.Debug/Echo', 'echo')).output]"`. +- `condition` - Optional. A string that DSC evaluates as a configuration expression. DSC only + returns the output when the condition evaluates to `true`. When it evaluates to any other value, + DSC skips the output. + +The schema also accepts a `copy` object in place of `value`, with the same shape as the `copy` +property of a resource instance. DSC doesn't currently support copy loops for outputs. When an +output defines `copy` instead of `value`, DSC raises a warning and skips the output. + +DSC doesn't evaluate outputs when you invoke the `dsc config set` command with the `--what-if` +option. + +For example, this document returns the value that the `echo` instance reported: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: echo + type: Microsoft.DSC.Debug/Echo + properties: + output: Hello World +outputs: + echoOutput: + type: string + value: "[reference(resourceId('Microsoft.DSC.Debug/Echo', 'echo')).output]" +``` ```yaml Type: object @@ -168,15 +413,33 @@ Parameters may be overridden at runtime, enabling re-use of the same configurati different contexts. For more information about defining parameters in a configuration, see -[DSC Configuration document parameter schema][02]. +[DSC Configuration document parameter schema][07]. +[DSC Configuration parameters][08] --> ```yaml Type: object Required: false -ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.parameter.json +ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/config/document.parameter.json +``` + +### resources + +The `resources` property defines a list of DSC Resource instances that the configuration manages. +Instances may share the same DSC Resource type, but every instance must have a unique combination +of `type` and `name`. If two instances share the same type and name, DSC raises an error. + +For more information about defining a valid resource instance in a configuration, see +[DSC Configuration document resource schema][09]. + + + +```yaml +Type: array +Required: true +ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/config/document.resource.json ``` ### variables @@ -190,37 +453,24 @@ which makes the document easier to read and maintain. Unlike parameters, variabl defined in the configuration and can't be overridden at runtime. +[DSC Configuration variables][12]. --> ```yaml Type: object Required: false ``` -### resources - -The `resources` property defines a list of DSC Resource instances that the configuration manages. -Every instance in the list must be unique, but instances may share the same DSC Resource type. - -For more information about defining a valid resource instance in a configuration, see -[DSC Configuration document resource schema][05]. - - - -```yaml -Type: array -Required: true -MinimumItemCount: 1 -ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.resource.json -``` - -[01]: functions/resourceId.md +[01]: functions/overview.md -[02]: parameter.md - - -[05]: resource.md - - +[02]: metadata.md +[03]: resource.md#requireversion +[04]: ../metadata/Microsoft.DSC/properties.md +[05]: ../definitions/parameters/dataTypes.md +[06]: functions/parameters.md +[07]: parameter.md + +[09]: resource.md + + + diff --git a/docs/reference/schemas/config/metadata.md b/docs/reference/schemas/config/metadata.md index c26bcc549..a6d638a6f 100644 --- a/docs/reference/schemas/config/metadata.md +++ b/docs/reference/schemas/config/metadata.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for metadata in a Desired State Configuration document. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Configuration document metadata schema --- @@ -38,12 +38,20 @@ metadata: Define a baseline for securing web application servers. ``` +The same schema applies to the `metadata` property of a resource instance in the configuration +document. For more information, see [DSC Configuration document resource instance schema][01]. + ## Microsoft.DSC The `Microsoft.DSC` metadata property contains directives and information that DSC itself uses when processing a configuration document. Unlike other metadata key-value pairs, DSC validates these properties. This property is reserved and shouldn't contain any custom user-defined metadata. +The schema for this property also accepts the execution information properties that DSC returns in +command output, like `operation` and `version`. DSC doesn't use those properties when it processes +a configuration document. For the full list of properties, see +[Microsoft.DSC metadata property schema reference][02]. + ### Properties #### securityContext @@ -52,31 +60,42 @@ This property defines the security context a configuration requires. If you invo against the configuration document in a security context that conflicts with this metadata, DSC raises an error when it validates the configuration document. +> [!NOTE] +> Defining the required security context in metadata is deprecated. DSC raises a warning when a +> configuration document defines this property. Use the `securityContext` directive in the +> document's [directives][03] property instead. If you define both, the values must match or DSC +> raises an error. + The valid security contexts are: -- `Current` +- `current` Indicates that the configuration document is usable under any security context. You can invoke DSC operations against the document when elevated as root or an administrator and as a normal user or account. -- `Elevated` +- `elevated` Indicates that the configuration document is usable only in an elevated security context. You can invoke DSC operations against the document when elevated as root or an administrator. When you invoke DSC operations against the document as a non-elevated user or account, DSC raises an error when it validates the configuration document. -- `Restricted` +- `restricted` Indicates that the configuration document is usable only in a non-elevated security context. You can invoke DSC operations against the document as a non-elevated user or account. When you invoke DSC operations against the document as root or an administrator, DSC raises an error when it validates the configuration document. -The default security context is `Current`. +The default security context is `current`. ```yaml -Type: object -Required: false -Default: Current -ValidValues: [Current, Elevated, Restricted] +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] ``` + + +[01]: resource.md#metadata-1 +[02]: ../metadata/Microsoft.DSC/properties.md +[03]: document.md#securitycontext diff --git a/docs/reference/schemas/config/parameter.md b/docs/reference/schemas/config/parameter.md index f76b803f2..d2300ebba 100644 --- a/docs/reference/schemas/config/parameter.md +++ b/docs/reference/schemas/config/parameter.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a parameter in a Desired State Configuration document. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Configuration document parameter schema --- @@ -79,7 +79,7 @@ For more information about data types, see ```yaml Type: string Required: true -ValidValues: [string, securestring, int, bool, object, secureobject, array] +ValidValues: [string, secureString, int, bool, object, secureObject, array] ``` ### defaultValue @@ -116,7 +116,7 @@ a string is its character count. The length of an array is its item count. If the default value or runtime value for the parameter is shorter than this property, DSC raises an error. If this property is defined for parameters whose `type` isn't `array`, `string`, or -`securestring`, DSC raises an error. +`secureString`, DSC raises an error. If this property is defined with the `maxLength` property, this property must be less than `maxLength`. If it isn't, DSC raises an error. @@ -134,7 +134,7 @@ a string is its character count. The length of an array is its item count. If the default value or runtime value for the parameter is longer than this property, DSC raises an error. If this property is defined for parameters whose `type` isn't `array`, `string`, or -`securestring`, DSC raises an error. +`secureString`, DSC raises an error. If this property is defined with the `minLength` property, this property must be greater than `minLength`. If it isn't, DSC raises an error. diff --git a/docs/reference/schemas/config/resource.md b/docs/reference/schemas/config/resource.md index 0af1a659f..50816718a 100644 --- a/docs/reference/schemas/config/resource.md +++ b/docs/reference/schemas/config/resource.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a resource instance in a Desired State Configuration document. -ms.date: 08/13/2026 +ms.date: 09/01/2026 ms.topic: reference title: DSC Configuration document resource instance schema --- @@ -21,9 +21,9 @@ Type: object ## Description -The `resources` property of a DSC Configuration document always includes at least one DSC Resource -instance. Together, the instances in a configuration define the desired state that DSC can get, -test, and set on a machine. +The `resources` property of a DSC Configuration document defines the DSC Resource instances for the +configuration. Together, the instances in a configuration define the desired state that DSC can +get, test, and set on a machine. This document describes the JSON schema for a valid DSC Resource instance in a configuration document. @@ -34,24 +34,34 @@ For more information about DSC Resources, see [Anatomy of a command-based DSC Re Every resource instance must be an object that defines these properties: -- [name](#name) - [type](#type) ## Properties -### name +### condition -The `name` property of a resource instance defines the short, human-readable name for a DSC -Resource instance. This property must be unique within a DSC Configuration document. If any -resource instances share the same name, DSC raises an error. +The `condition` property defines an expression that DSC evaluates before invoking the instance. If +the expression evaluates to `true`, DSC invokes the instance as normal. If it evaluates to any other +value, DSC skips the instance and doesn't include it in the results for the operation. -The instance name must be a non-empty string containing only letters, numbers, and spaces. +For example, DSC only invokes this instance when the `enableFeature` parameter is `true`: ```yaml -Type: string -Required: true -MinimumLength: 1 -Pattern: ^[a-zA-Z0-9 ]+$ +parameters: + enableFeature: + type: bool + defaultValue: false +resources: + - name: Feature + type: Microsoft.DSC.Debug/Echo + condition: "[parameters('enableFeature')]" + properties: + output: Feature enabled +``` + +```yaml +Type: string +Required: false ``` ### type @@ -63,20 +73,111 @@ valid fully qualified type name for the resource. For more information about typ ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ ``` -### properties +### requireVersion -The `properties` of a resource instance define its desired state. The value of this property must -be an object. For assertion resources, the value can be an empty object (`{}`). DSC uses the -DSC Resource's instance schema to validate the defined properties. +The `requireVersion` property pins the instance to a specific version or a range of versions of the +resource. DSC only invokes a discovered resource whose version satisfies the requirement and raises +an error if it can't find one. When this property isn't defined, DSC doesn't constrain the version +of the resource. + +Define the value as a semantic version requirement: one or more comparators separated by commas. +Each comparator is an operator (`=`, `>`, `>=`, `<`, `<=`, `^`, or `~`) followed by a version. +Build metadata isn't allowed in the version. For example: + +- `=1.2.3` - exactly version `1.2.3`. +- `>=1.2.3, <2.0.0` - any version from `1.2.3` up to, but not including, `2.0.0`. +- `^1.2` - any version from `1.2.0` up to, but not including, `2.0.0`. +- `~2.3` - any version from `2.3.0` up to, but not including, `2.4.0`. + +For compatibility with resources that use date versions, the value can also be a date version like +`2026-02-03` or `2026-11-27-preview`. A date version requirement only matches a resource with +exactly the same date version. Date versions are deprecated. Use semantic versions instead. + +This property has the alias `apiVersion`. You can define the requirement with either property name, +but not both. + +```yaml +Type: string +Required: false +``` + +### name + +The `name` property defines the short, human-readable name for the instance. DSC uses the name +together with the `type` to identify the instance in results and messages, and for the +[resourceId()][02] function. The combination of `type` and `name` must be unique within a +configuration document. If two instances share the same type and name, DSC raises an error. + +The value can be a configuration expression, like `"[format('Server-{0}', copyIndex())]"` for an +instance in a copy loop. DSC evaluates the expression to a string before invoking the instance. + +Although the schema doesn't require this property, always define a unique name for every instance. +When the property isn't defined, DSC uses an empty string as the name. + +```yaml +Type: string +Required: false +Default: "" +``` - +### directives + +The `directives` property of a resource instance defines per-instance overrides for how DSC should +process the resource. This property was added in DSC version 3.2. ```yaml Type: object -Required: true +Required: false +``` + +You can define the following directives for a resource instance: + +#### requireAdapter + +The `requireAdapter` directive indicates that DSC should use the specified adapter to invoke the +adapted resource instance. The value for this directive must be the fully qualified type name of +the adapter resource, like `Microsoft.Adapter/PowerShell`. + +When this directive isn't specified, DSC invokes the adapted resource through the first discovered +adapter that indicates it can invoke the resource. This directive has no effect on nonadapted +resource instances. + +```yaml +Type: string +Required: false +Pattern: ^\w+(\.\w+)*\/\w+$ +``` + +#### securityContext + +The `securityContext` directive indicates that DSC should validate the current security context +against this directive before invoking the resource. This value overrides the +`directives.securityContext` setting for the top level of the configuration document. This enables +you to selectively require or forbid elevated security contexts for a specific resource instance. + +```yaml +Type: string +Required: false +ValidValues: [current, elevated, restricted] +``` + +### executionInformation + +The `executionInformation` property describes the DSC operation that produced the instance. DSC +adds this property to every instance in the configuration document returned by the +`dsc config export` command. The schema accepts this property for any instance, but DSC ignores it +when it processes a configuration document. + +The value is an object with the same properties as the [Microsoft.DSC metadata][03] object that DSC +returns in command output, plus an optional `whatIf` property that describes any what-if +operations DSC performed. + +```yaml +Type: object +Required: false ``` ### dependsOn @@ -85,15 +186,14 @@ To declare that a resource instance is dependent on another instance in the conf the `dependsOn` property. This property defines a list of DSC Resource instances that DSC must successfully process before -processing this instance. Each value for this property must be the [resourceID() function][02] -lookup for another instance in the configuration. Multiple instances can depend on the same -instance, but every dependency for an instance must be unique in that instance's `dependsOn` -property. +processing this instance. Each value for this property must be an expression that uses the +[resourceId() function][02] to look up another instance in the configuration. Multiple instances +can depend on the same instance. -The `resourceID()` function uses this syntax: +The `resourceId()` function uses this syntax: ```yaml -"[resourceId('', '']" +"[resourceId('', '')]" ``` The `` value is the `type` property of the dependent resource and @@ -120,8 +220,12 @@ resource named `Tailspin Key`: - "[resourceId('Microsoft.Windows/Registry', 'Tailspin Key')]" ``` +For an instance in a copy loop, you can use the [copyIndex()][04] function in the expression to +depend on the matching iteration of another copy loop, like +`"[resourceId('Microsoft.DSC.Debug/Echo', format('Policy-{0}', copyIndex()))]"`. + > [!NOTE] -> When defining dependencies for [nested resource instances][03], instances can only reference +> When defining dependencies for [nested resource instances][05], instances can only reference > dependencies in the same resource provider or group instance. They can't use the `resourceId()` > function to lookup instances at the top-level of the configuration document or inside another > provider or group instance. @@ -130,64 +234,112 @@ resource named `Tailspin Key`: > the instance of the provider or group containing the dependency instance instead. For more information about using functions in configuration documents, see -[DSC Configuration document functions reference][04]. For more information about the `resourceId()` +[DSC Configuration document functions reference][06]. For more information about the `resourceId()` function, see [resourceId][02]. ```yaml -Type: array -Required: false -ItemsMustBeUnique: true -ItemsType: string -ItemsPattern: ^\[resourceId\(\s*'\w+(\.\w+){0,2}\/\w+'\s*,\s*'[a-zA-Z0-9 ]+'\s*\)\]$ +Type: array +Required: false +ItemsType: string ``` -### directives +### copy -The `directives` property of a resource instance defines per-instance overrides for how DSC should -process the resource. This property was added in DSC version 3.2. +The `copy` property defines a copy loop that expands the instance into multiple instances that +share the same definition. Before invoking any resources, DSC creates one instance for each +iteration of the loop. Use the [copyIndex()][04] function in the instance's `name`, `properties`, +and `dependsOn` expressions to make each expanded instance unique. The `name` of an instance in a +copy loop must be an expression that evaluates to a different string for every iteration. + +> [!IMPORTANT] +> Copy loops are deprecated. DSC raises a warning when a configuration document uses the `copy` +> property. The functionality remains available for compatibility but will be removed in DSC +> version 4.0.0. For more information, see [DSC issue #1429][07]. + +The value for this property is an object with the following properties: + +- `name` - Required. The name of the copy loop. Pass this name to `copyIndex()` to get the current + iteration index for a specific loop. +- `count` - Required. The number of iterations, as an integer or an expression that evaluates to an + integer, like `"[parameters('serverCount')]"`. A count of `0` expands to no instances. +- `mode` - Optional. Reserved for future use. The schema accepts the values `serial` and + `parallel`, but DSC raises an error if you define this property. +- `batchSize` - Optional. Reserved for future use. The schema accepts an integer or an expression, + but DSC raises an error if you define this property. + +For example, this instance expands into the `Server-0` and `Server-1` instances: + +```yaml +resources: + - name: "[format('Server-{0}', copyIndex())]" + type: Microsoft.DSC.Debug/Echo + copy: + name: serverLoop + count: 2 + properties: + output: "[format('Instance-{0}', copyIndex())]" +``` ```yaml Type: object Required: false ``` -You can define the following directives for a resource instance: - -#### requireAdapter +### properties -The `requireAdapter` directive indicates that DSC should use the specified adapter to invoke the -adapted resource instance. The value for this directive must be the fully qualified type name of -the adapter resource, like `Microsoft.Adapter/PowerShell`. +The `properties` of a resource instance define its desired state. The value of this property must +be an object. For assertion resources, the value can be an empty object (`{}`). DSC uses the +DSC Resource's instance schema to validate the defined properties. -When this directive isn't specified, DSC invokes the adapted resource through the first discovered -adapter that indicates it can invoke the resource. This directive has no effect on nonadapted -resource instances. + ```yaml -Type: string +Type: object Required: false -Pattern: ^\w+(\.\w+){0,2}\/\w+$ ``` -#### securityContext +### resources -The `securityContext` directive indicates that DSC should validate the current security context -against this directive before invoking the resource. This value overrides the -`metadata.Microsoft.DSC.securityContext` setting for the top level of the configuration document. -This enables you to selectively require or forbid elevated security contexts for a specific -resource instance. +The `resources` property defines a list of nested resource instances that use the same schema as a +top-level instance. This property mirrors the shape of a resource in an Azure Resource Manager +(ARM) template. The schema accepts this property, but DSC doesn't currently process instances +defined in it. To manage nested instances, use a group resource like `Microsoft.DSC/Group` and +define the nested instances in the group's `properties`. ```yaml -Type: string -Required: false -ValidValues: [Current, Elevated, Restricted] +Type: array +Required: false +ItemsType: object +``` + +### metadata + +The `metadata` property defines a set of key-value pairs as annotations for the resource instance. +Except for the `Microsoft.DSC` property, DSC doesn't validate the metadata. When DSC invokes the +resource, it passes the metadata to the resource as the `_metadata` property of the instance if the +resource's instance schema allows it. For adapters that accept the full configuration as input, DSC +passes the metadata as the `metadata` property instead. + +The `Microsoft.DSC` property is reserved for DSC. DSC honors the deprecated `securityContext` +setting in this property for the instance, and adds the `copyLoops` property to instances it +expands from a copy loop. For more information, see +[DSC Configuration document metadata schema][08]. + +```yaml +Type: object +Required: false ``` + [01]: ../definitions/resourceType.md [02]: functions/resourceId.md -[03]: ../../../glossary.md#nested-resource-instance -[04]: functions/overview.md +[03]: ../metadata/Microsoft.DSC/properties.md +[04]: functions/copyIndex.md +[05]: ../../../glossary.md#nested-resource-instance +[06]: functions/overview.md +[07]: https://github.com/PowerShell/DSC/issues/1429 +[08]: metadata.md