diff --git a/docs/reference/schemas/config/functions/overview.md b/docs/reference/schemas/config/functions/overview.md index e71ee8e83..305e0b85e 100644 --- a/docs/reference/schemas/config/functions/overview.md +++ b/docs/reference/schemas/config/functions/overview.md @@ -698,6 +698,10 @@ The following list of functions are for manipulating strings: The following list of functions provide system-level information: - [path()][path] - Construct a file system path from one or more path segments. +- [restartRequired()][restartRequired] - Return whether a system, service, or process requires a + restart. +- [stateChanged()][stateChanged] - Return whether a resource instance changed state during a + `set` operation. - [systemRoot()][systemRoot] - Return the system root directory path. - [utcNow()][utcNow] - Return the current UTC datetime in a specified format. @@ -767,9 +771,11 @@ The following list of functions create or convert values of a given type: [range]: ./range.md [reference]: ./reference.md [resourceId]: ./resourceId.md +[restartRequired]: ./restartRequired.md [secret]: ./secret.md [skip]: ./skip.md [startsWith]: ./startsWith.md +[stateChanged]: ./stateChanged.md [string]: ./string.md [take]: ./take.md [sub]: ./sub.md diff --git a/docs/reference/schemas/config/functions/restartRequired.md b/docs/reference/schemas/config/functions/restartRequired.md new file mode 100644 index 000000000..3193f37a3 --- /dev/null +++ b/docs/reference/schemas/config/functions/restartRequired.md @@ -0,0 +1,119 @@ +--- +description: Reference for the 'restartRequired' DSC configuration document function +ms.date: 07/11/2026 +ms.topic: reference +title: restartRequired +--- + +# restartRequired + +## Synopsis + +Returns whether a system, service, or process requires a restart. + +## Syntax + +```Syntax +restartRequired('system') +restartRequired('service', '') +restartRequired('process', '') +``` + +## Description + +The `restartRequired()` function returns whether a resource in the current configuration operation +reported a required restart. DSC aggregates restart requirements returned by resources in the +configuration context. + +Use `system` to query whether a system restart is required. Use `service` or `process` to query a +specific service or process by name. For `service` and `process`, the `name` argument is required. +For `system`, the `name` argument isn't allowed. + +The function returns `false` when no matching restart requirement has been reported. + +## Examples + +### Example 1 - Query restart requirements + +This configuration queries whether installing the OpenSSH Client capability with the +[Microsoft.Windows/FeatureOnDemandList][01] resource requires a system restart. When the resource +reports a system restart requirement, `restartRequired()` returns `true`. + +> [!NOTE] +> This example requires Windows, an elevated session, and access to a Windows Update or WSUS +> source. Capability installation does not always require a restart. + +```yaml +# restartRequired.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Install OpenSSH Client + type: Microsoft.Windows/FeatureOnDemandList + properties: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed +outputs: + systemRestartRequired: + type: bool + value: "[restartRequired('system')]" +``` + +```bash +dsc config set --file restartRequired.example.1.dsc.config.yaml +``` + +When the resource instances report the corresponding restart requirements, DSC returns: + +```yaml +outputs: + systemRestartRequired: true +``` + +To query a service or process restart requirement, specify its name as the second argument: + +```Syntax +restartRequired('service', 'example-service') +restartRequired('process', 'example-process') +``` + +## Parameters + +### kind + +The kind of restart requirement to query. The value must be `process`, `service`, or `system`. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +AllowedValues: +- process +- service +- system +``` + +### name + +The name of the process or service to query. This argument is required when **kind** is `process` +or `service`, and it isn't allowed when **kind** is `system`. + +```yaml +Type: string +Required: conditional +MinimumCount: 0 +MaximumCount: 1 +``` + +## Output + +The `restartRequired()` function returns `true` when a matching restart requirement was reported +by a resource in the current configuration operation. Otherwise, it returns `false`. + +```yaml +Type: bool +``` + + +[01]: ../../../resources/Microsoft/Windows/FeatureOnDemandList/index.md diff --git a/docs/reference/schemas/config/functions/stateChanged.md b/docs/reference/schemas/config/functions/stateChanged.md new file mode 100644 index 000000000..ff91a2c6d --- /dev/null +++ b/docs/reference/schemas/config/functions/stateChanged.md @@ -0,0 +1,107 @@ +--- +description: Reference for the 'stateChanged' DSC configuration document function +ms.date: 07/11/2026 +ms.topic: reference +title: stateChanged +--- + +# stateChanged + +## Synopsis + +Returns whether a resource instance changed state during the current `set` operation. + +## Syntax + +```Syntax +stateChanged(resourceId('', '')) +``` + +## Description + +The `stateChanged()` function returns `true` when the referenced resource instance changed one or +more properties during the current `set` operation. Otherwise, it returns `false`. + +The function can only evaluate an instance after DSC has executed it. Use [resourceId()][01] to +identify the instance and add that instance to the calling resource's [dependsOn][02] property. +When DSC evaluates `stateChanged()` for an instance that has not run or does not exist, it returns +an error. + +## Examples + +### Example 1 - Report whether a resource changed state + +The configuration sets the **Install OpenSSH Client** instance with the +[Microsoft.Windows/FeatureOnDemandList][03] resource and then runs the **Report change** instance. +The second instance uses `stateChanged()` to report whether the feature resource changed state. Its +`dependsOn` property ensures the feature instance has completed before DSC evaluates the function. + +> [!NOTE] +> This example requires Windows, an elevated session, and access to a Windows Update or WSUS +> source. The output is `true` only when installing the feature changes state. + +```yaml +# stateChanged.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Install OpenSSH Client + type: Microsoft.Windows/FeatureOnDemandList + properties: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed +- name: Report change + type: Microsoft.DSC.Debug/Echo + properties: + output: "[stateChanged(resourceId('Microsoft.Windows/FeatureOnDemandList', 'Install OpenSSH Client'))]" + dependsOn: + - "[resourceId('Microsoft.Windows/FeatureOnDemandList', 'Install OpenSSH Client')]" +``` + +```bash +dsc config set --file stateChanged.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Install OpenSSH Client + type: Microsoft.Windows/FeatureOnDemandList + result: + changedProperties: + - capabilities +- name: Report change + type: Microsoft.DSC.Debug/Echo + result: + afterState: + output: true +messages: [] +hadErrors: false +``` + +## Parameters + +### resourceId + +The resource ID of the instance whose state change information you want to retrieve. Use the +[resourceId()][01] function to create this value. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `stateChanged()` function returns `true` if the resource changed one or more properties in the +current `set` operation. Otherwise, it returns `false`. + +```yaml +Type: bool +``` + + +[01]: ./resourceId.md +[02]: ../resource.md#dependson +[03]: ../../../resources/Microsoft/Windows/FeatureOnDemandList/index.md