From 5e555352b1a3830a625efb4cb3c323c8fdebd189 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 3 Jun 2025 07:12:02 +0200 Subject: [PATCH 01/13] Add reference documentation for rebootPending and WindowsPowerShell --- .../Microsoft/DSC/PowerShell/index.md | 12 +- .../OSInfo/examples/osinfo.config.dsc.yaml | 2 +- .../examples/check-for-pending-reboot.md | 43 +++ .../examples/pendingReboot.config.dsc.yaml | 19 ++ .../use-rebootpending-in-configuration.md | 253 +++++++++++++++++ .../Microsoft/Windows/RebootPending/index.md | 128 +++++++++ .../examples/manage-a-windows-service.md | 228 ++++++++++++++++ .../Windows/WindowsPowerShell/index.md | 254 ++++++++++++++++++ 8 files changed, 935 insertions(+), 4 deletions(-) create mode 100644 docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md create mode 100644 docs/reference/resources/Microsoft/Windows/RebootPending/examples/pendingReboot.config.dsc.yaml create mode 100644 docs/reference/resources/Microsoft/Windows/RebootPending/examples/use-rebootpending-in-configuration.md create mode 100644 docs/reference/resources/Microsoft/Windows/WindowsPowerShell/examples/manage-a-windows-service.md diff --git a/docs/reference/resources/Microsoft/DSC/PowerShell/index.md b/docs/reference/resources/Microsoft/DSC/PowerShell/index.md index db56a0d2f..48583b73e 100644 --- a/docs/reference/resources/Microsoft/DSC/PowerShell/index.md +++ b/docs/reference/resources/Microsoft/DSC/PowerShell/index.md @@ -32,6 +32,12 @@ resources: - name: type: / properties: # adapted resource properties + +# Or from v3.1.0-preview.2 onwards +resources: +- name: + type: / + properties: # adapted resource properties ``` ## Description @@ -42,7 +48,7 @@ implemented as PowerShell classes. The adapter manages the PSDSC resources in PowerShell, not Windows PowerShell. To use MOF-based PSDSC resources or PSDSC resources that require Windows PowerShell, use the -[Microsoft.Windows/WindowsPowerShell](../../windows/windowspowershell/resource.md) adapter. +[Microsoft.Windows/WindowsPowerShell](../../windows/windowspowershell/index.md) adapter. This adapter doesn't use the **PSDesiredStateConfiguration** module. You don't need to install the **PSDesiredStateConfiguration** module to use PSDSC resources in DSC through this adapter. @@ -62,7 +68,7 @@ for each platform. | macOS | `$HOME/.dsc/PSAdapterCache.json` | | Windows | `%LOCALAPPDATA%\dsc\PSAdapterCache.json` | -The adapter versions the cache. The current version is `1`. If the version of the cache on a +The adapter versions the cache. The current version is `2`. If the version of the cache on a machine differs from the current version, the adapter refreshes the cache. The adapter checks whether the cache is stale on each run and refreshes it if: @@ -82,7 +88,7 @@ $adapterScript = dsc resource list Microsoft.DSC/PowerShell | Select-Object -ExpandProperty directory | Join-Path -& $adapterScript -Operation CLearCache +& $adapterScript -Operation ClearCache ``` ## Requirements diff --git a/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml b/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml index 4ab824969..45d571104 100644 --- a/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml +++ b/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml @@ -9,4 +9,4 @@ resources: - name: Is64BitOS type: Microsoft/OSInfo properties: - bitness: '32' + bitness: '64' diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md new file mode 100644 index 000000000..ec4340bc4 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md @@ -0,0 +1,43 @@ +--- +description: > + Example showing how to use the Microsoft.Windows/RebootPending resource with DSC to check if a Windows system has a pending reboot. +ms.date: 03/25/2025 +ms.topic: reference +title: Check for pending reboot +--- + +# Check for pending reboot + +This example shows how you can use the `Microsoft.Windows/RebootPending` resource to check whether a Windows system has a pending reboot. + +## Check reboot status + +The following snippet shows how to use the resource with the [dsc resource get][01] command to retrieve the pending reboot status. + +```powershell +dsc resource get --resource Microsoft.Windows/RebootPending +``` + +When you run this command, DSC returns the following result if a reboot is pending: + +```yaml +actualState: + rebootPending: true +``` + +If no reboot is pending, the result is: + +```yaml +actualState: + rebootPending: false +``` + +The `rebootPending` property indicates whether the system requires a reboot (`true`) or not (`false`). + +> [!NOTE] +> The `Microsoft.Windows/RebootPending` resource is read-only. +> You can only use the **Get** operation to check the reboot status. +> The resource does not support **Set**, **WhatIf**, **Export**, **Delete**, or **Test** operations. + + +[01]: ../../../../../cli/resource/get.md \ No newline at end of file diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/examples/pendingReboot.config.dsc.yaml b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/pendingReboot.config.dsc.yaml new file mode 100644 index 000000000..9824a2dbf --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/pendingReboot.config.dsc.yaml @@ -0,0 +1,19 @@ +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Managed key + type: Microsoft.Windows/Registry + properties: + _exist: true + keyPath: HKCU\DscExamples\ManagedKey + dependsOn: + - "[resourceId('Microsoft.DSC/Assertion','Assert pending reboot')]" +- name: Assert pending reboot + type: Microsoft.DSC/Assertion + properties: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Check pending reboot + type: Microsoft.Windows/RebootPending + properties: + rebootPending: true diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/examples/use-rebootpending-in-configuration.md b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/use-rebootpending-in-configuration.md new file mode 100644 index 000000000..31c7196a2 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/use-rebootpending-in-configuration.md @@ -0,0 +1,253 @@ +--- +description: > + Example showing how to use the Microsoft.Windows/RebootPending resource in a + configuration document with an assertion to check for a pending reboot. +ms.date: 03/25/2025 +ms.topic: reference +title: Use RebootPending resource in a configuration +--- + +# Use the RebootPending resource in a configuration + +This example demonstrates how to use the `Microsoft.Windows/RebootPending` resource in a configuration document. +The configuration checks if a reboot is pending and, if so, skips the subsequent step using an assertion. + +## Definition + +This configuration document demonstrates how to use the `Microsoft.Windows/RebootPending` resource together with an assertion. + +The first instance defines the desired state for the `ManagedKey` registry key, ensuring it +exists only if no reboot is pending. It uses the `dependsOn` property to reference the assertion resource, +which checks the system's reboot status using the `Microsoft.Windows/RebootPending` resource. +The assertion passes when `rebootPending` is `false`,allowing the registry key resource to run. +If a reboot is pending, the assertion fails and the registry key is not set. + +:::code language="yaml" source="pendingReboot.config.dsc.yaml"::: + +Copy the configuration document and save it as `pendingReboot.config.dsc.yaml`. + +## Test configuration + +To see whether the system is in the desired state, use the [dsc config test][01] command on the +configuration document. + +```powershell +dsc config test --file ./pendingReboot.config.dsc.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: test + executionType: actual + startDatetime: 2025-06-03T06:49:22.573486200+02:00 + endDatetime: 2025-06-03T06:49:35.813770500+02:00 + duration: PT13.2402843S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT10.0162818S + name: Assert pending reboot + type: Microsoft.DSC/Assertion + result: + desiredState: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Check pending reboot + type: Microsoft.Windows/RebootPending + properties: + rebootPending: false + actualState: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + contentVersion: 1.0.0 + resources: + - type: Microsoft.Windows/RebootPending + name: Check pending reboot + properties: + rebootPending: false + inDesiredState: true + differingProperties: [] +- metadata: + Microsoft.DSC: + duration: PT0.0549784S + name: Managed key + type: Microsoft.Windows/Registry + result: + desiredState: + _exist: true + keyPath: HKCU\DscExamples\ManagedKey + actualState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false + inDesiredState: false + differingProperties: + - _exist +messages: [] +hadErrors: false +``` + +Review the individual results to understand whether each instance is in the desired state. + +The result for the first instance, named `Check pending reboot`, was: + +```yaml +desiredState: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Check pending reboot + type: Microsoft.Windows/RebootPending + properties: + rebootPending: false +actualState: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + contentVersion: 1.0.0 + resources: + - type: Microsoft.Windows/RebootPending + name: Check pending reboot + properties: + rebootPending: false +inDesiredState: true +differingProperties: [] +``` + +The output indicates there is no pending reboot. When you use the **Set** operation on +this confifguration, the second instance will run. + +The result for the second instance, named `Managed value`, was: + +```yaml +desiredState: + _exist: true + keyPath: HKCU\DscExamples\ManagedKey +actualState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false +inDesiredState: false +differingProperties: +- _exist +``` + +The output indicates the registry path doesn't exist. + +The first instance indicates the resource is in the desired state. The second +instance indicates it isn't in the desired state. + +## Enforce configuration + +To update the system to the desired state, use the [dsc config set][02] command on the configuration document. + +```powershell +dsc config set --file ./pendingReboot.config.dsc.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: set + executionType: actual + startDatetime: 2025-06-03T06:55:12.123456+02:00 + endDatetime: 2025-06-03T06:55:15.654321+02:00 + duration: PT3.530865S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT2.000000S + name: Assert pending reboot + type: Microsoft.DSC/Assertion + result: + beforeState: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Check pending reboot + type: Microsoft.Windows/RebootPending + properties: + rebootPending: false + afterState: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Check pending reboot + type: Microsoft.Windows/RebootPending + properties: + rebootPending: false + changedProperties: [] +- metadata: + Microsoft.DSC: + duration: PT0.0549784S + name: Managed key + type: Microsoft.Windows/Registry + result: + beforeState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false + afterState: + keyPath: HKCU\DscExamples\ManagedKey + changedProperties: + - _exist +messages: [] +hadErrors: false +``` + +Review the individual results to understand how the resource modified the system to enforce the desired state for each instance. + +The result for the assertion instance, named `Assert pending reboot`, was: + +```yaml +beforeState: +- name: Check pending reboot + type: Microsoft.Windows/RebootPending + result: + actualState: + rebootPending: false +afterState: +- metadata: + Microsoft.DSC: + duration: PT0.5209322S + name: Check pending reboot + type: Microsoft.Windows/RebootPending + result: + desiredState: + rebootPending: false + actualState: + rebootPending: false + inDesiredState: true + differingProperties: [] +changedProperties: [] +``` + +The output indicates the assertion passed and no changes were needed. + +The result for the registry key instance, named `Managed key`, was: + +```yaml +beforeState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false +afterState: + keyPath: HKCU\DscExamples\ManagedKey +changedProperties: +- _exist +``` + +The output indicates that the resource created the registry key. + +## Cleanup + +To return your system to its original state: + +1. Save the following configuration as `registry.cleanup.config.dsc.yaml`. + + :::code language="yaml" source="../../Registry/examples/registry.cleanup.config.dsc.yaml"::: + +2. Use the **Set** operation on the cleanup configuration document. + + ```powershell + dsc config set --file ./registry.cleanup.config.dsc.yaml + ``` + + +[01]: ../../../../../cli/config/test.md +[02]: ../../../../../cli/config/set.md \ No newline at end of file diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md index e69de29bb..665c68857 100644 --- a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md @@ -0,0 +1,128 @@ +--- +description: Microsoft.Windows/RebootPending resource reference documentation +ms.date: 03/25/2025 +ms.topic: reference +title: Microsoft.Windows/RebootPending +--- + +# Microsoft.Windows/RebootPending + +## Synopsis + +Checks if a Windows system has a pending reboot. + +> [!IMPORTANT] +> The `Microsoft.Windows/RebootPending` resource are a proof-of-concept example +> for use with DSC. Don't use it in production. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [Windows] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.Windows/RebootPending + properties: {} +``` + +## Description + +The `Microsoft.Windows/RebootPending` resource enables you to check whether a Windows system has a pending reboot. The resource can determine if a system reboot is required due to: + +- Windows Updates +- Component-Based Servicing +- Pending file rename operations +- Pending computer rename +- Pending domain join operations + +> [!NOTE] +> This resource is installed with DSC itself on Windows systems. +> +> You can update this resource by updating DSC. When you update DSC, the updated version of this +> resource is automatically available. + +## Requirements + +- The resource is only usable on a Windows system. +- The resource must run in a process context that has permissions to query the system for reboot status. + +## Capabilities + +The resource has the following capabilities: + +- `get` - You can use the resource to retrieve the pending reboot status of a system. + +This resource does not support `set`, `whatIf`, `export`, `test`, or `delete` operations. For more information about resource capabilities, see [DSC resource capabilities][02]. + +## Examples + +1. [Check for pending reboot][03] - Shows how to check if a system has a pending reboot using the `dsc resource get` command. +2. [Use the RebootPending resource in a configuration][04] - Shows how to include the RebootPending resource in a configuration document to check reboot status. + +## Properties + +The resource doesn't have any configurable properties. It's a read-only resource designed to detect a system's reboot status. + +- **Read-only properties:** The resource returns the following properties. For more information about read-only properties, see the "Read-only resource properties" section in [DSC resource properties][08]. + + - [rebootPending](#rebootpending) - Indicates whether the system has a pending reboot. + +### rebootPending + +
Expand for rebootPending property metadata + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : true +IsWriteOnly : false +``` + +
+ +A boolean value that indicates whether the system has a pending reboot. `true` if a reboot is pending; otherwise, `false`. + +## Instance validating schema + +The following snippet contains the JSON Schema that validates an instance of the resource. + +```json +{ +"type": "null", + "properties": { + "rebootPending": { + "type": "boolean", + "readOnly": true + } + } +} +``` + +## Exit codes + +The resource doesn't return any specific exit codes. It reports status through the `rebootPending` property. + +## See also + +- [Microsoft.Windows/Registry resource][10] +- [Windows Registry][11] +- [DSC resource capabilities][02] +- [DSC resource properties][06] + + +[02]: ../../../../../concepts/resources/capabilities.md +[03]: ./examples/check-for-pending-reboot.md +[04]: ./examples/use-rebootpending-in-configuration.md +[06]: ../../../../../concepts/resources/properties.md +[08]: ../../../../../concepts/resources/properties.md#read-only-resource-properties +[10]: ../registry/index.md +[11]: /windows/win32/sysinfo/about-the-registry diff --git a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/examples/manage-a-windows-service.md b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/examples/manage-a-windows-service.md new file mode 100644 index 000000000..9fa9cbf12 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/examples/manage-a-windows-service.md @@ -0,0 +1,228 @@ +--- +description: > + Examples showing how you can invoke the Microsoft.Windows/WindowsPowerShell with DSC to manage + a Windows service using the PSDesiredStateConfiguration module. + +ms.date: 03/25/2025 +ms.topic: reference +title: Manage a Windows service +--- + +This example shows how you can use the `Microsoft.Windows/WindowsPowerShell` resource with the `PSDesiredStateConfiguration` module to manage a Windows service. +These examples manage the `Spooler` print spooler service. + +> [!NOTE] +> Run this example in an elevated PowerShell session with `dsc.exe` version 3.1.0-preview.2 or later. + +## Test whether a service is running + +The following snippet shows how you can use the resource with the [dsc resource test][01] command to check whether the `Spooler` service is running. + +```powershell +$instance = @{ + Name = 'Spooler' + StartupType = 'Automatic' +} | ConvertTo-Json + +dsc resource test --resource PSDesiredStateConfiguration/Service --input $instance +``` + +When the service isn't running or has a different startup type, DSC returns the following result: + +```yaml +desiredState: + Name: Spooler + StartupType: Manual +actualState: + InDesiredState: false +inDesiredState: false +differingProperties: +- StartupType +``` + +The `inDesiredState` field of the result object is set to `false`, indicating that the instance isn't in the desired state. The `differingProperties` field indicates that the `property` property is mismatched between the desired state and actual state. + +## Ensure a service is running with automatic startup + +To set the system to the desired state and configure the service, use the [dsc resource set][02] command. + +```powershell +dsc resource set --resource PSDesiredStateConfiguration/Service --input $instance +``` + +When the resource configures the service, DSC returns the following result: + +```yaml +beforeState: + Status: null / + Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers. + DisplayName: Print Spooler + ResourceId: null + PsDscRunAsCredential: null + Name: Spooler + Credential: null + PSComputerName: localhost + ConfigurationName: null + Ensure: null + DependsOn: null + SourceInfo: null + BuiltInAccount: LocalSystem + StartupType: Manual + State: Running + ModuleVersion: '1.1' + ModuleName: PSDesiredStateConfiguration + Path: C:\WINDOWS\System32\spoolsv.exe + Dependencies: + - RPCSS + - http +afterState: + Status: null + Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers. + DisplayName: Print Spooler + ResourceId: null + PsDscRunAsCredential: null + Name: Spooler + Credential: null + PSComputerName: localhost + ConfigurationName: null + Ensure: null + DependsOn: null + SourceInfo: null + BuiltInAccount: LocalSystem + StartupType: Automatic + State: Running + ModuleVersion: '1.1' + ModuleName: PSDesiredStateConfiguration + Path: C:\WINDOWS\System32\spoolsv.exe + Dependencies: + - RPCSS + - http +changedProperties: +- StartupType +``` + +You can test the instance again to confirm that the service is configured correctly: + +```powershell +dsc resource test --resource PSDesiredStateConfiguration/Service --input $instance +``` + +```yaml +desiredState: + Name: Spooler + StartupType: Manual +actualState: + InDesiredState: true +inDesiredState: true +differingProperties: [] +``` + +## Stop a service + +The following snippet shows how you can configure the `Spooler` service to be stopped with manual startup. + +```powershell +$stopInstance = @{ + Name = 'Spooler' + State = 'Stopped' + StartupType = 'Manual' +} | ConvertTo-Json + +dsc resource set --resource PSDesiredStateConfiguration/Service --input $stopInstance +``` + +When the resource stops the service, DSC returns the following result: + +```yaml +beforeState: + Status: null + Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers. + DisplayName: Print Spooler + ResourceId: null + PsDscRunAsCredential: null + Name: Spooler + Credential: null + PSComputerName: localhost + ConfigurationName: null + Ensure: null + DependsOn: null + SourceInfo: null + BuiltInAccount: LocalSystem + StartupType: Manual + State: Running + ModuleVersion: '1.1' + ModuleName: PSDesiredStateConfiguration + Path: C:\WINDOWS\System32\spoolsv.exe + Dependencies: + - RPCSS + - http +afterState: + Status: null + Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers. + DisplayName: Print Spooler + ResourceId: null + PsDscRunAsCredential: null + Name: Spooler + Credential: null + PSComputerName: localhost + ConfigurationName: null + Ensure: null + DependsOn: null + SourceInfo: null + BuiltInAccount: LocalSystem + StartupType: Manual + State: Stopped + ModuleVersion: '1.1' + ModuleName: PSDesiredStateConfiguration + Path: C:\WINDOWS\System32\spoolsv.exe + Dependencies: + - RPCSS + - http +changedProperties: +- State +``` + +## Verify the current state of a service + +To check the current state of the service, use the `dsc resource get` command. + +```powershell +dsc resource get --resource PSDesiredStateConfiguration/Service --input $instance +``` + +```yaml +actualState: + Status: null + Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers. + DisplayName: Print Spooler + ResourceId: null + PsDscRunAsCredential: null + Name: Spooler + Credential: null + PSComputerName: localhost + ConfigurationName: null + Ensure: null + DependsOn: null + SourceInfo: null + BuiltInAccount: LocalSystem + StartupType: Manual + State: Stopped + ModuleVersion: '1.1' + ModuleName: PSDesiredStateConfiguration + Path: C:\WINDOWS\System32\spoolsv.exe + Dependencies: + - RPCSS + - http +``` + +## Restore the original service configuration + +If you want to restore the service to its original running state, you can reapply the first configuration. + +```powershell +dsc resource set --resource Microsoft.Windows/WindowsPowerShell --input $instance +``` + + +[01]: ../../../../../cli/resource/test.md +[02]: ../../../../../cli/resource/set.md \ No newline at end of file diff --git a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md index e69de29bb..255239888 100644 --- a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md +++ b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md @@ -0,0 +1,254 @@ +--- +description: Microsoft.Windows/WindowsPowerShell resource adapter reference documentation +ms.date: 03/25/2025 +ms.topic: reference +title: Microsoft.Windows/WindowsPowerShell +--- + +# Microsoft.Windows/WindowsPowerShell + +## Synopsis + +Adapter for resources implemented as binary, script or PowerShell classes. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [windows, powershell] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.Windows/WindowsPowerShell + properties: + # Required properties + resources: + - name: + type: / + properties: # adapted resource properties + +# Or from v3.1.0-preview.2 onwards +resources: +- name: + type: / + properties: # adapted resource properties +``` + +## Description + +The `Microsoft.Windows/WindowsPowerShell` resource adapter enables you to invoke and discover PSDSC resources. The resource can: + +- Execute script-based DSC resources +- Run class-based DSC resource methods +- Execute binary DSC resources + +The adapter manages the PDSC resources in Windows PowerShell, not PowerShell. To use PowerShell classes in PowerShell, use the [Microsoft.DSC/PowerShell](../../dsc/powershell/index.md) adapter. + +This adapter uses the **PSDesiredStateConfiguration** module v1.1. This module is built-in when you install Windows and is located in `%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules` + +### PowerShell resource adapter cache + +The process for discovering the Windows PowerShell resources available to the adapter can be +time-consuming. To improve performance, the adapter caches Windows PowerShell resources and modules during +discovery. If the cache doesn't exist during discovery, the adapter creates it. + +The location of the cache depends on your operating system. The following table defines the path +for the Windows platform. + +| Platform | Path | +| :------: | :----------------------------------------| +| Windows | `%LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json` | + +The adapter versions the cache. The current version is `1`. If the version of the cache on a +machine differs from the current version, the adapter refreshes the cache. + +The adapter checks whether the cache is stale on each run and refreshes it if: + +- The `PSModulePath` environmental variable is updated. +- Any module is added or removed from the `PSModulePath`. +- Any related file in a cached PSDSC resource module has been updated since the cache was written. + The adapter watches the `LastWriteTime` property of module files with the following extensions: + `.ps1`, `.psd1`, and `.psm1`. + +You can directly call the adapter script to clear the cache with the **Operation** parameter value +set to `ClearCache`: + +```powershell +$adapterScript = dsc resource list Microsoft.Windows/WindowsPowerShell | + ConvertFrom-Json | + Select-Object -ExpandProperty directory | + Join-Path + +& $adapterScript -Operation ClearCache +``` + +## Requirements + +- The resource is only usable on a Windows system. +- The resource must run in a process context that has appropriate permissions for the DSC resource to be executed. +- The PowerShell modules exposing DSC resources should be installed in + `%PROGRAMFILES%\WindowsPowerShell\Modules` or + `%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules` + +## Capabilities + +The resource adapter has the following capabilities: + +- `get` - You can use the resource to retrieve the actual state of a DSC resource instance. +- `set` - You can use the resource to enforce the desired state for a DSC resource instance. +- `test` - You can use the resource to determine whether a DSC resource instance is in the desired state. +- `export` - You can use the resource to discover and enumerate DSC resource instances currently installed and available on the system. +- `list` - Lists available PowerShell DSC resources on your system that can be used with `dsc.exe`. + +> [!NOTE] +> The `export` capability is only available with class-based DSC resources. +> Script-based and binary DSC resources do not support the export operation. + +## Examples + +1. [Manage a Windows Service][01] - Shows how to manage a Windows service + +## Properties + +Unlike standard resources, the `Microsoft.Windows/WindowsPowerShell` resource adapter doesn't have directly exposed properties +in its schema because it acts as a bridge to PowerShell DSC resource. Instead, the adapter: + +1. Dynamically discovers the property schema for each PowerShell DSC resource +2. Stores the schema properties in a cache file for improved performance in subsequent operations +3. Passes properties to the underlying PowerShell DSC resource + +The adapter maintains a cache of resource schemas at: + +- Windows: `%LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json` + +To list the schema properties for a PowerShell DSC resource, you can run the following command: + +```powershell +dsc resource list --adapter Microsoft.Windows/WindowsPowerShell / | + ConvertFrom-Json | + Select-Object properties +``` + +You can also retrieve more information by directly reading it from the cache file: + +```powershell +$cache = Get-Content -Path "$env:LOCALAPPDATA\dsc\WindowsPSAdapterCache.json" | + ConvertFrom-Json + +($cache.ResourceCache | Where-Object -Property type -EQ '/').DscResourceInfo.Properties +``` + +When defining a configuration document, the following properties are required. + +### resources + +The `resources` property defines a list of adapted PSDSC resource instances that the adapter 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 adapted resource instance, see the +[Adapted resource instances](#adapted-resource-instances) section of this document. + +```yaml +Type: array +Required: true +MinimumItemCount: 1 +ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.resource.json +``` + +## Adapted resource instances + +Adapted resources instances always adhere to the +[DSC Configuration document resource instance schema](../../../../schemas/config/resource.md). + +Every adapted instance must be an object that defines the [name](#adapted-instance-name), +[type](#adapted-instance-type), and [properties](#adapted-instance-properties) for the instance. + +### Adapted instance name + +The `name` property of the adapted resource instance defines the short, human-readable name for the +instance. The adapted instance name must be a non-empty string containing only letters, numbers, +and spaces. This property should be unique within the adapter's `resources` array. + +> ![NOTE] +> The adapter doesn't currently raise an error when you define two adapted instances with the same +> name. In a future release, the adapter will be updated to emit a warning when adapted instances +> share the same name. In the next major version of the adapter, name conflicts will raise an +> error. +> +> Using the same name for multiple instances can make debugging and reviewing output more +> difficult. Always use unique names for every instance. + +```yaml +PropertyName: name +Type: string +Required: true +MinimumLength: 1 +Pattern: ^[a-zA-Z0-9 ]+$ +``` + +### Adapted instance type + +The `type` property identifies the adapted instance's PSDSC Resource. The value for this property +must be the valid fully qualified type name for the resource. + +This adapter uses the following syntax for determining the fully qualified type name of a PSDSC +resource implemented as a PowerShell class: + +```Syntax +/ +``` + +For example, if a PowerShell module named **TailspinToys** has a class-based PSDSC resource named +`TSToy`, the fully qualified type name for that resource is `TailspinToys/TSToy`. + +For more information about type names in DSC, see +[DSC Resource fully qualified type name schema reference][02]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### Adapted instance properties + +The `properties` of an adapted resource instance define its desired state. The value of this +property must be an object. The specified properties are validated at runtime when the adapter +tries to invoke the adapted PSDSC resource instance. This adapter doesn't support static linting +for adapted instance properties in a configuration document. + +Each name for each property must be a configurable property of the PSDSC resource. The property +name isn't case sensitive. The value for each property must be valid for that property. If you +specify an invalid property name or value, the adapter raises an error when it tries to invoke the +resource. + +```yaml +Type: object +Required: true +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Error + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed because the underlying DSC resource method or `Invoke-DscResource` call did not succeed. +When the resource returns this exit code, it also emits an error message with details about the failure. + + +[01]: ./examples/manage-a-windows-service.md +[02]: ../../../../schemas/config/type.md \ No newline at end of file From 272b9d2d7d100404eb69990f3c9193a696236cbb Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 3 Jun 2025 07:12:45 +0200 Subject: [PATCH 02/13] Revert change on OSInfo --- .../resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml b/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml index 45d571104..4ab824969 100644 --- a/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml +++ b/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml @@ -9,4 +9,4 @@ resources: - name: Is64BitOS type: Microsoft/OSInfo properties: - bitness: '64' + bitness: '32' From b833ecab5c7ac95b2df5a690cff638f7eb13e8e4 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 3 Jun 2025 07:19:28 +0200 Subject: [PATCH 03/13] Fix link definitions --- .../examples/check-for-pending-reboot.md | 1 - .../Microsoft/Windows/RebootPending/index.md | 23 +++++++++---------- 2 files changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md index ec4340bc4..cd83f8b65 100644 --- a/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md @@ -35,7 +35,6 @@ actualState: The `rebootPending` property indicates whether the system requires a reboot (`true`) or not (`false`). > [!NOTE] -> The `Microsoft.Windows/RebootPending` resource is read-only. > You can only use the **Get** operation to check the reboot status. > The resource does not support **Set**, **WhatIf**, **Export**, **Delete**, or **Test** operations. diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md index 665c68857..3e284ab54 100644 --- a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md @@ -64,14 +64,14 @@ This resource does not support `set`, `whatIf`, `export`, `test`, or `delete` op ## Examples -1. [Check for pending reboot][03] - Shows how to check if a system has a pending reboot using the `dsc resource get` command. -2. [Use the RebootPending resource in a configuration][04] - Shows how to include the RebootPending resource in a configuration document to check reboot status. +1. [Check for pending reboot][04] - Shows how to check if a system has a pending reboot using the `dsc resource get` command. +2. [Use the RebootPending resource in a configuration][05] - Shows how to include the RebootPending resource in a configuration document to check reboot status. ## Properties The resource doesn't have any configurable properties. It's a read-only resource designed to detect a system's reboot status. -- **Read-only properties:** The resource returns the following properties. For more information about read-only properties, see the "Read-only resource properties" section in [DSC resource properties][08]. +- **Read-only properties:** The resource returns the following properties. For more information about read-only properties, see the "Read-only resource properties" section in [DSC resource properties][03]. - [rebootPending](#rebootpending) - Indicates whether the system has a pending reboot. @@ -113,16 +113,15 @@ The resource doesn't return any specific exit codes. It reports status through t ## See also -- [Microsoft.Windows/Registry resource][10] -- [Windows Registry][11] +- [Microsoft.Windows/Registry resource][01] - [DSC resource capabilities][02] -- [DSC resource properties][06] +- [DSC resource properties][03] +- [Check for pending reboot][04] +- [Use the RebootPending resource in a configuration][05] +[01]: ../registry/index.md [02]: ../../../../../concepts/resources/capabilities.md -[03]: ./examples/check-for-pending-reboot.md -[04]: ./examples/use-rebootpending-in-configuration.md -[06]: ../../../../../concepts/resources/properties.md -[08]: ../../../../../concepts/resources/properties.md#read-only-resource-properties -[10]: ../registry/index.md -[11]: /windows/win32/sysinfo/about-the-registry +[03]: ../../../../../concepts/resources/properties.md +[04]: ./examples/check-for-pending-reboot.md +[05]: ./examples/use-rebootpending-in-configuration.md From 0d193f60a5bbae15f5c3b5ca1fccbc3a6c920616 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 3 Jun 2025 07:20:19 +0200 Subject: [PATCH 04/13] Format table --- .../resources/Microsoft/Windows/WindowsPowerShell/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md index 255239888..b84317386 100644 --- a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md +++ b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md @@ -61,8 +61,8 @@ discovery. If the cache doesn't exist during discovery, the adapter creates it. The location of the cache depends on your operating system. The following table defines the path for the Windows platform. -| Platform | Path | -| :------: | :----------------------------------------| +| Platform | Path | +| :------: | :---------------------------------------------- | | Windows | `%LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json` | The adapter versions the cache. The current version is `1`. If the version of the cache on a From c8e9c5175be1305e33b4727d83910de9c4f819c7 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 3 Jun 2025 07:21:32 +0200 Subject: [PATCH 05/13] Clarification on script-based --- .../resources/Microsoft/Windows/WindowsPowerShell/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md index b84317386..e27e09fbb 100644 --- a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md +++ b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md @@ -198,13 +198,13 @@ The `type` property identifies the adapted instance's PSDSC Resource. The value must be the valid fully qualified type name for the resource. This adapter uses the following syntax for determining the fully qualified type name of a PSDSC -resource implemented as a PowerShell class: +resource implemented as a Windows PowerShell script-based: ```Syntax -/ +/ ``` -For example, if a PowerShell module named **TailspinToys** has a class-based PSDSC resource named +For example, if a PowerShell module named **TailspinToys** has a script-based PSDSC resource named `TSToy`, the fully qualified type name for that resource is `TailspinToys/TSToy`. For more information about type names in DSC, see From 67496da5047860af41399e45d08f0694ce960b54 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 3 Jun 2025 07:12:02 +0200 Subject: [PATCH 06/13] Add reference documentation for rebootPending and WindowsPowerShell --- .../Microsoft/DSC/PowerShell/index.md | 12 +- .../OSInfo/examples/osinfo.config.dsc.yaml | 2 +- .../examples/check-for-pending-reboot.md | 43 +++ .../examples/pendingReboot.config.dsc.yaml | 19 ++ .../use-rebootpending-in-configuration.md | 253 +++++++++++++++++ .../Microsoft/Windows/RebootPending/index.md | 128 +++++++++ .../examples/manage-a-windows-service.md | 228 ++++++++++++++++ .../Windows/WindowsPowerShell/index.md | 254 ++++++++++++++++++ 8 files changed, 935 insertions(+), 4 deletions(-) create mode 100644 docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md create mode 100644 docs/reference/resources/Microsoft/Windows/RebootPending/examples/pendingReboot.config.dsc.yaml create mode 100644 docs/reference/resources/Microsoft/Windows/RebootPending/examples/use-rebootpending-in-configuration.md create mode 100644 docs/reference/resources/Microsoft/Windows/WindowsPowerShell/examples/manage-a-windows-service.md diff --git a/docs/reference/resources/Microsoft/DSC/PowerShell/index.md b/docs/reference/resources/Microsoft/DSC/PowerShell/index.md index db56a0d2f..48583b73e 100644 --- a/docs/reference/resources/Microsoft/DSC/PowerShell/index.md +++ b/docs/reference/resources/Microsoft/DSC/PowerShell/index.md @@ -32,6 +32,12 @@ resources: - name: type: / properties: # adapted resource properties + +# Or from v3.1.0-preview.2 onwards +resources: +- name: + type: / + properties: # adapted resource properties ``` ## Description @@ -42,7 +48,7 @@ implemented as PowerShell classes. The adapter manages the PSDSC resources in PowerShell, not Windows PowerShell. To use MOF-based PSDSC resources or PSDSC resources that require Windows PowerShell, use the -[Microsoft.Windows/WindowsPowerShell](../../windows/windowspowershell/resource.md) adapter. +[Microsoft.Windows/WindowsPowerShell](../../windows/windowspowershell/index.md) adapter. This adapter doesn't use the **PSDesiredStateConfiguration** module. You don't need to install the **PSDesiredStateConfiguration** module to use PSDSC resources in DSC through this adapter. @@ -62,7 +68,7 @@ for each platform. | macOS | `$HOME/.dsc/PSAdapterCache.json` | | Windows | `%LOCALAPPDATA%\dsc\PSAdapterCache.json` | -The adapter versions the cache. The current version is `1`. If the version of the cache on a +The adapter versions the cache. The current version is `2`. If the version of the cache on a machine differs from the current version, the adapter refreshes the cache. The adapter checks whether the cache is stale on each run and refreshes it if: @@ -82,7 +88,7 @@ $adapterScript = dsc resource list Microsoft.DSC/PowerShell | Select-Object -ExpandProperty directory | Join-Path -& $adapterScript -Operation CLearCache +& $adapterScript -Operation ClearCache ``` ## Requirements diff --git a/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml b/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml index 4ab824969..45d571104 100644 --- a/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml +++ b/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml @@ -9,4 +9,4 @@ resources: - name: Is64BitOS type: Microsoft/OSInfo properties: - bitness: '32' + bitness: '64' diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md new file mode 100644 index 000000000..ec4340bc4 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md @@ -0,0 +1,43 @@ +--- +description: > + Example showing how to use the Microsoft.Windows/RebootPending resource with DSC to check if a Windows system has a pending reboot. +ms.date: 03/25/2025 +ms.topic: reference +title: Check for pending reboot +--- + +# Check for pending reboot + +This example shows how you can use the `Microsoft.Windows/RebootPending` resource to check whether a Windows system has a pending reboot. + +## Check reboot status + +The following snippet shows how to use the resource with the [dsc resource get][01] command to retrieve the pending reboot status. + +```powershell +dsc resource get --resource Microsoft.Windows/RebootPending +``` + +When you run this command, DSC returns the following result if a reboot is pending: + +```yaml +actualState: + rebootPending: true +``` + +If no reboot is pending, the result is: + +```yaml +actualState: + rebootPending: false +``` + +The `rebootPending` property indicates whether the system requires a reboot (`true`) or not (`false`). + +> [!NOTE] +> The `Microsoft.Windows/RebootPending` resource is read-only. +> You can only use the **Get** operation to check the reboot status. +> The resource does not support **Set**, **WhatIf**, **Export**, **Delete**, or **Test** operations. + + +[01]: ../../../../../cli/resource/get.md \ No newline at end of file diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/examples/pendingReboot.config.dsc.yaml b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/pendingReboot.config.dsc.yaml new file mode 100644 index 000000000..9824a2dbf --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/pendingReboot.config.dsc.yaml @@ -0,0 +1,19 @@ +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Managed key + type: Microsoft.Windows/Registry + properties: + _exist: true + keyPath: HKCU\DscExamples\ManagedKey + dependsOn: + - "[resourceId('Microsoft.DSC/Assertion','Assert pending reboot')]" +- name: Assert pending reboot + type: Microsoft.DSC/Assertion + properties: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Check pending reboot + type: Microsoft.Windows/RebootPending + properties: + rebootPending: true diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/examples/use-rebootpending-in-configuration.md b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/use-rebootpending-in-configuration.md new file mode 100644 index 000000000..31c7196a2 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/use-rebootpending-in-configuration.md @@ -0,0 +1,253 @@ +--- +description: > + Example showing how to use the Microsoft.Windows/RebootPending resource in a + configuration document with an assertion to check for a pending reboot. +ms.date: 03/25/2025 +ms.topic: reference +title: Use RebootPending resource in a configuration +--- + +# Use the RebootPending resource in a configuration + +This example demonstrates how to use the `Microsoft.Windows/RebootPending` resource in a configuration document. +The configuration checks if a reboot is pending and, if so, skips the subsequent step using an assertion. + +## Definition + +This configuration document demonstrates how to use the `Microsoft.Windows/RebootPending` resource together with an assertion. + +The first instance defines the desired state for the `ManagedKey` registry key, ensuring it +exists only if no reboot is pending. It uses the `dependsOn` property to reference the assertion resource, +which checks the system's reboot status using the `Microsoft.Windows/RebootPending` resource. +The assertion passes when `rebootPending` is `false`,allowing the registry key resource to run. +If a reboot is pending, the assertion fails and the registry key is not set. + +:::code language="yaml" source="pendingReboot.config.dsc.yaml"::: + +Copy the configuration document and save it as `pendingReboot.config.dsc.yaml`. + +## Test configuration + +To see whether the system is in the desired state, use the [dsc config test][01] command on the +configuration document. + +```powershell +dsc config test --file ./pendingReboot.config.dsc.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: test + executionType: actual + startDatetime: 2025-06-03T06:49:22.573486200+02:00 + endDatetime: 2025-06-03T06:49:35.813770500+02:00 + duration: PT13.2402843S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT10.0162818S + name: Assert pending reboot + type: Microsoft.DSC/Assertion + result: + desiredState: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Check pending reboot + type: Microsoft.Windows/RebootPending + properties: + rebootPending: false + actualState: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + contentVersion: 1.0.0 + resources: + - type: Microsoft.Windows/RebootPending + name: Check pending reboot + properties: + rebootPending: false + inDesiredState: true + differingProperties: [] +- metadata: + Microsoft.DSC: + duration: PT0.0549784S + name: Managed key + type: Microsoft.Windows/Registry + result: + desiredState: + _exist: true + keyPath: HKCU\DscExamples\ManagedKey + actualState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false + inDesiredState: false + differingProperties: + - _exist +messages: [] +hadErrors: false +``` + +Review the individual results to understand whether each instance is in the desired state. + +The result for the first instance, named `Check pending reboot`, was: + +```yaml +desiredState: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Check pending reboot + type: Microsoft.Windows/RebootPending + properties: + rebootPending: false +actualState: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + contentVersion: 1.0.0 + resources: + - type: Microsoft.Windows/RebootPending + name: Check pending reboot + properties: + rebootPending: false +inDesiredState: true +differingProperties: [] +``` + +The output indicates there is no pending reboot. When you use the **Set** operation on +this confifguration, the second instance will run. + +The result for the second instance, named `Managed value`, was: + +```yaml +desiredState: + _exist: true + keyPath: HKCU\DscExamples\ManagedKey +actualState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false +inDesiredState: false +differingProperties: +- _exist +``` + +The output indicates the registry path doesn't exist. + +The first instance indicates the resource is in the desired state. The second +instance indicates it isn't in the desired state. + +## Enforce configuration + +To update the system to the desired state, use the [dsc config set][02] command on the configuration document. + +```powershell +dsc config set --file ./pendingReboot.config.dsc.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.0.0 + operation: set + executionType: actual + startDatetime: 2025-06-03T06:55:12.123456+02:00 + endDatetime: 2025-06-03T06:55:15.654321+02:00 + duration: PT3.530865S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT2.000000S + name: Assert pending reboot + type: Microsoft.DSC/Assertion + result: + beforeState: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Check pending reboot + type: Microsoft.Windows/RebootPending + properties: + rebootPending: false + afterState: + $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json + resources: + - name: Check pending reboot + type: Microsoft.Windows/RebootPending + properties: + rebootPending: false + changedProperties: [] +- metadata: + Microsoft.DSC: + duration: PT0.0549784S + name: Managed key + type: Microsoft.Windows/Registry + result: + beforeState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false + afterState: + keyPath: HKCU\DscExamples\ManagedKey + changedProperties: + - _exist +messages: [] +hadErrors: false +``` + +Review the individual results to understand how the resource modified the system to enforce the desired state for each instance. + +The result for the assertion instance, named `Assert pending reboot`, was: + +```yaml +beforeState: +- name: Check pending reboot + type: Microsoft.Windows/RebootPending + result: + actualState: + rebootPending: false +afterState: +- metadata: + Microsoft.DSC: + duration: PT0.5209322S + name: Check pending reboot + type: Microsoft.Windows/RebootPending + result: + desiredState: + rebootPending: false + actualState: + rebootPending: false + inDesiredState: true + differingProperties: [] +changedProperties: [] +``` + +The output indicates the assertion passed and no changes were needed. + +The result for the registry key instance, named `Managed key`, was: + +```yaml +beforeState: + keyPath: HKCU\DscExamples\ManagedKey + _exist: false +afterState: + keyPath: HKCU\DscExamples\ManagedKey +changedProperties: +- _exist +``` + +The output indicates that the resource created the registry key. + +## Cleanup + +To return your system to its original state: + +1. Save the following configuration as `registry.cleanup.config.dsc.yaml`. + + :::code language="yaml" source="../../Registry/examples/registry.cleanup.config.dsc.yaml"::: + +2. Use the **Set** operation on the cleanup configuration document. + + ```powershell + dsc config set --file ./registry.cleanup.config.dsc.yaml + ``` + + +[01]: ../../../../../cli/config/test.md +[02]: ../../../../../cli/config/set.md \ No newline at end of file diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md index e69de29bb..665c68857 100644 --- a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md @@ -0,0 +1,128 @@ +--- +description: Microsoft.Windows/RebootPending resource reference documentation +ms.date: 03/25/2025 +ms.topic: reference +title: Microsoft.Windows/RebootPending +--- + +# Microsoft.Windows/RebootPending + +## Synopsis + +Checks if a Windows system has a pending reboot. + +> [!IMPORTANT] +> The `Microsoft.Windows/RebootPending` resource are a proof-of-concept example +> for use with DSC. Don't use it in production. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [Windows] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.Windows/RebootPending + properties: {} +``` + +## Description + +The `Microsoft.Windows/RebootPending` resource enables you to check whether a Windows system has a pending reboot. The resource can determine if a system reboot is required due to: + +- Windows Updates +- Component-Based Servicing +- Pending file rename operations +- Pending computer rename +- Pending domain join operations + +> [!NOTE] +> This resource is installed with DSC itself on Windows systems. +> +> You can update this resource by updating DSC. When you update DSC, the updated version of this +> resource is automatically available. + +## Requirements + +- The resource is only usable on a Windows system. +- The resource must run in a process context that has permissions to query the system for reboot status. + +## Capabilities + +The resource has the following capabilities: + +- `get` - You can use the resource to retrieve the pending reboot status of a system. + +This resource does not support `set`, `whatIf`, `export`, `test`, or `delete` operations. For more information about resource capabilities, see [DSC resource capabilities][02]. + +## Examples + +1. [Check for pending reboot][03] - Shows how to check if a system has a pending reboot using the `dsc resource get` command. +2. [Use the RebootPending resource in a configuration][04] - Shows how to include the RebootPending resource in a configuration document to check reboot status. + +## Properties + +The resource doesn't have any configurable properties. It's a read-only resource designed to detect a system's reboot status. + +- **Read-only properties:** The resource returns the following properties. For more information about read-only properties, see the "Read-only resource properties" section in [DSC resource properties][08]. + + - [rebootPending](#rebootpending) - Indicates whether the system has a pending reboot. + +### rebootPending + +
Expand for rebootPending property metadata + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : true +IsWriteOnly : false +``` + +
+ +A boolean value that indicates whether the system has a pending reboot. `true` if a reboot is pending; otherwise, `false`. + +## Instance validating schema + +The following snippet contains the JSON Schema that validates an instance of the resource. + +```json +{ +"type": "null", + "properties": { + "rebootPending": { + "type": "boolean", + "readOnly": true + } + } +} +``` + +## Exit codes + +The resource doesn't return any specific exit codes. It reports status through the `rebootPending` property. + +## See also + +- [Microsoft.Windows/Registry resource][10] +- [Windows Registry][11] +- [DSC resource capabilities][02] +- [DSC resource properties][06] + + +[02]: ../../../../../concepts/resources/capabilities.md +[03]: ./examples/check-for-pending-reboot.md +[04]: ./examples/use-rebootpending-in-configuration.md +[06]: ../../../../../concepts/resources/properties.md +[08]: ../../../../../concepts/resources/properties.md#read-only-resource-properties +[10]: ../registry/index.md +[11]: /windows/win32/sysinfo/about-the-registry diff --git a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/examples/manage-a-windows-service.md b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/examples/manage-a-windows-service.md new file mode 100644 index 000000000..9fa9cbf12 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/examples/manage-a-windows-service.md @@ -0,0 +1,228 @@ +--- +description: > + Examples showing how you can invoke the Microsoft.Windows/WindowsPowerShell with DSC to manage + a Windows service using the PSDesiredStateConfiguration module. + +ms.date: 03/25/2025 +ms.topic: reference +title: Manage a Windows service +--- + +This example shows how you can use the `Microsoft.Windows/WindowsPowerShell` resource with the `PSDesiredStateConfiguration` module to manage a Windows service. +These examples manage the `Spooler` print spooler service. + +> [!NOTE] +> Run this example in an elevated PowerShell session with `dsc.exe` version 3.1.0-preview.2 or later. + +## Test whether a service is running + +The following snippet shows how you can use the resource with the [dsc resource test][01] command to check whether the `Spooler` service is running. + +```powershell +$instance = @{ + Name = 'Spooler' + StartupType = 'Automatic' +} | ConvertTo-Json + +dsc resource test --resource PSDesiredStateConfiguration/Service --input $instance +``` + +When the service isn't running or has a different startup type, DSC returns the following result: + +```yaml +desiredState: + Name: Spooler + StartupType: Manual +actualState: + InDesiredState: false +inDesiredState: false +differingProperties: +- StartupType +``` + +The `inDesiredState` field of the result object is set to `false`, indicating that the instance isn't in the desired state. The `differingProperties` field indicates that the `property` property is mismatched between the desired state and actual state. + +## Ensure a service is running with automatic startup + +To set the system to the desired state and configure the service, use the [dsc resource set][02] command. + +```powershell +dsc resource set --resource PSDesiredStateConfiguration/Service --input $instance +``` + +When the resource configures the service, DSC returns the following result: + +```yaml +beforeState: + Status: null / + Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers. + DisplayName: Print Spooler + ResourceId: null + PsDscRunAsCredential: null + Name: Spooler + Credential: null + PSComputerName: localhost + ConfigurationName: null + Ensure: null + DependsOn: null + SourceInfo: null + BuiltInAccount: LocalSystem + StartupType: Manual + State: Running + ModuleVersion: '1.1' + ModuleName: PSDesiredStateConfiguration + Path: C:\WINDOWS\System32\spoolsv.exe + Dependencies: + - RPCSS + - http +afterState: + Status: null + Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers. + DisplayName: Print Spooler + ResourceId: null + PsDscRunAsCredential: null + Name: Spooler + Credential: null + PSComputerName: localhost + ConfigurationName: null + Ensure: null + DependsOn: null + SourceInfo: null + BuiltInAccount: LocalSystem + StartupType: Automatic + State: Running + ModuleVersion: '1.1' + ModuleName: PSDesiredStateConfiguration + Path: C:\WINDOWS\System32\spoolsv.exe + Dependencies: + - RPCSS + - http +changedProperties: +- StartupType +``` + +You can test the instance again to confirm that the service is configured correctly: + +```powershell +dsc resource test --resource PSDesiredStateConfiguration/Service --input $instance +``` + +```yaml +desiredState: + Name: Spooler + StartupType: Manual +actualState: + InDesiredState: true +inDesiredState: true +differingProperties: [] +``` + +## Stop a service + +The following snippet shows how you can configure the `Spooler` service to be stopped with manual startup. + +```powershell +$stopInstance = @{ + Name = 'Spooler' + State = 'Stopped' + StartupType = 'Manual' +} | ConvertTo-Json + +dsc resource set --resource PSDesiredStateConfiguration/Service --input $stopInstance +``` + +When the resource stops the service, DSC returns the following result: + +```yaml +beforeState: + Status: null + Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers. + DisplayName: Print Spooler + ResourceId: null + PsDscRunAsCredential: null + Name: Spooler + Credential: null + PSComputerName: localhost + ConfigurationName: null + Ensure: null + DependsOn: null + SourceInfo: null + BuiltInAccount: LocalSystem + StartupType: Manual + State: Running + ModuleVersion: '1.1' + ModuleName: PSDesiredStateConfiguration + Path: C:\WINDOWS\System32\spoolsv.exe + Dependencies: + - RPCSS + - http +afterState: + Status: null + Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers. + DisplayName: Print Spooler + ResourceId: null + PsDscRunAsCredential: null + Name: Spooler + Credential: null + PSComputerName: localhost + ConfigurationName: null + Ensure: null + DependsOn: null + SourceInfo: null + BuiltInAccount: LocalSystem + StartupType: Manual + State: Stopped + ModuleVersion: '1.1' + ModuleName: PSDesiredStateConfiguration + Path: C:\WINDOWS\System32\spoolsv.exe + Dependencies: + - RPCSS + - http +changedProperties: +- State +``` + +## Verify the current state of a service + +To check the current state of the service, use the `dsc resource get` command. + +```powershell +dsc resource get --resource PSDesiredStateConfiguration/Service --input $instance +``` + +```yaml +actualState: + Status: null + Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers. + DisplayName: Print Spooler + ResourceId: null + PsDscRunAsCredential: null + Name: Spooler + Credential: null + PSComputerName: localhost + ConfigurationName: null + Ensure: null + DependsOn: null + SourceInfo: null + BuiltInAccount: LocalSystem + StartupType: Manual + State: Stopped + ModuleVersion: '1.1' + ModuleName: PSDesiredStateConfiguration + Path: C:\WINDOWS\System32\spoolsv.exe + Dependencies: + - RPCSS + - http +``` + +## Restore the original service configuration + +If you want to restore the service to its original running state, you can reapply the first configuration. + +```powershell +dsc resource set --resource Microsoft.Windows/WindowsPowerShell --input $instance +``` + + +[01]: ../../../../../cli/resource/test.md +[02]: ../../../../../cli/resource/set.md \ No newline at end of file diff --git a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md index e69de29bb..255239888 100644 --- a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md +++ b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md @@ -0,0 +1,254 @@ +--- +description: Microsoft.Windows/WindowsPowerShell resource adapter reference documentation +ms.date: 03/25/2025 +ms.topic: reference +title: Microsoft.Windows/WindowsPowerShell +--- + +# Microsoft.Windows/WindowsPowerShell + +## Synopsis + +Adapter for resources implemented as binary, script or PowerShell classes. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [windows, powershell] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.Windows/WindowsPowerShell + properties: + # Required properties + resources: + - name: + type: / + properties: # adapted resource properties + +# Or from v3.1.0-preview.2 onwards +resources: +- name: + type: / + properties: # adapted resource properties +``` + +## Description + +The `Microsoft.Windows/WindowsPowerShell` resource adapter enables you to invoke and discover PSDSC resources. The resource can: + +- Execute script-based DSC resources +- Run class-based DSC resource methods +- Execute binary DSC resources + +The adapter manages the PDSC resources in Windows PowerShell, not PowerShell. To use PowerShell classes in PowerShell, use the [Microsoft.DSC/PowerShell](../../dsc/powershell/index.md) adapter. + +This adapter uses the **PSDesiredStateConfiguration** module v1.1. This module is built-in when you install Windows and is located in `%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules` + +### PowerShell resource adapter cache + +The process for discovering the Windows PowerShell resources available to the adapter can be +time-consuming. To improve performance, the adapter caches Windows PowerShell resources and modules during +discovery. If the cache doesn't exist during discovery, the adapter creates it. + +The location of the cache depends on your operating system. The following table defines the path +for the Windows platform. + +| Platform | Path | +| :------: | :----------------------------------------| +| Windows | `%LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json` | + +The adapter versions the cache. The current version is `1`. If the version of the cache on a +machine differs from the current version, the adapter refreshes the cache. + +The adapter checks whether the cache is stale on each run and refreshes it if: + +- The `PSModulePath` environmental variable is updated. +- Any module is added or removed from the `PSModulePath`. +- Any related file in a cached PSDSC resource module has been updated since the cache was written. + The adapter watches the `LastWriteTime` property of module files with the following extensions: + `.ps1`, `.psd1`, and `.psm1`. + +You can directly call the adapter script to clear the cache with the **Operation** parameter value +set to `ClearCache`: + +```powershell +$adapterScript = dsc resource list Microsoft.Windows/WindowsPowerShell | + ConvertFrom-Json | + Select-Object -ExpandProperty directory | + Join-Path + +& $adapterScript -Operation ClearCache +``` + +## Requirements + +- The resource is only usable on a Windows system. +- The resource must run in a process context that has appropriate permissions for the DSC resource to be executed. +- The PowerShell modules exposing DSC resources should be installed in + `%PROGRAMFILES%\WindowsPowerShell\Modules` or + `%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules` + +## Capabilities + +The resource adapter has the following capabilities: + +- `get` - You can use the resource to retrieve the actual state of a DSC resource instance. +- `set` - You can use the resource to enforce the desired state for a DSC resource instance. +- `test` - You can use the resource to determine whether a DSC resource instance is in the desired state. +- `export` - You can use the resource to discover and enumerate DSC resource instances currently installed and available on the system. +- `list` - Lists available PowerShell DSC resources on your system that can be used with `dsc.exe`. + +> [!NOTE] +> The `export` capability is only available with class-based DSC resources. +> Script-based and binary DSC resources do not support the export operation. + +## Examples + +1. [Manage a Windows Service][01] - Shows how to manage a Windows service + +## Properties + +Unlike standard resources, the `Microsoft.Windows/WindowsPowerShell` resource adapter doesn't have directly exposed properties +in its schema because it acts as a bridge to PowerShell DSC resource. Instead, the adapter: + +1. Dynamically discovers the property schema for each PowerShell DSC resource +2. Stores the schema properties in a cache file for improved performance in subsequent operations +3. Passes properties to the underlying PowerShell DSC resource + +The adapter maintains a cache of resource schemas at: + +- Windows: `%LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json` + +To list the schema properties for a PowerShell DSC resource, you can run the following command: + +```powershell +dsc resource list --adapter Microsoft.Windows/WindowsPowerShell / | + ConvertFrom-Json | + Select-Object properties +``` + +You can also retrieve more information by directly reading it from the cache file: + +```powershell +$cache = Get-Content -Path "$env:LOCALAPPDATA\dsc\WindowsPSAdapterCache.json" | + ConvertFrom-Json + +($cache.ResourceCache | Where-Object -Property type -EQ '/').DscResourceInfo.Properties +``` + +When defining a configuration document, the following properties are required. + +### resources + +The `resources` property defines a list of adapted PSDSC resource instances that the adapter 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 adapted resource instance, see the +[Adapted resource instances](#adapted-resource-instances) section of this document. + +```yaml +Type: array +Required: true +MinimumItemCount: 1 +ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.resource.json +``` + +## Adapted resource instances + +Adapted resources instances always adhere to the +[DSC Configuration document resource instance schema](../../../../schemas/config/resource.md). + +Every adapted instance must be an object that defines the [name](#adapted-instance-name), +[type](#adapted-instance-type), and [properties](#adapted-instance-properties) for the instance. + +### Adapted instance name + +The `name` property of the adapted resource instance defines the short, human-readable name for the +instance. The adapted instance name must be a non-empty string containing only letters, numbers, +and spaces. This property should be unique within the adapter's `resources` array. + +> ![NOTE] +> The adapter doesn't currently raise an error when you define two adapted instances with the same +> name. In a future release, the adapter will be updated to emit a warning when adapted instances +> share the same name. In the next major version of the adapter, name conflicts will raise an +> error. +> +> Using the same name for multiple instances can make debugging and reviewing output more +> difficult. Always use unique names for every instance. + +```yaml +PropertyName: name +Type: string +Required: true +MinimumLength: 1 +Pattern: ^[a-zA-Z0-9 ]+$ +``` + +### Adapted instance type + +The `type` property identifies the adapted instance's PSDSC Resource. The value for this property +must be the valid fully qualified type name for the resource. + +This adapter uses the following syntax for determining the fully qualified type name of a PSDSC +resource implemented as a PowerShell class: + +```Syntax +/ +``` + +For example, if a PowerShell module named **TailspinToys** has a class-based PSDSC resource named +`TSToy`, the fully qualified type name for that resource is `TailspinToys/TSToy`. + +For more information about type names in DSC, see +[DSC Resource fully qualified type name schema reference][02]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### Adapted instance properties + +The `properties` of an adapted resource instance define its desired state. The value of this +property must be an object. The specified properties are validated at runtime when the adapter +tries to invoke the adapted PSDSC resource instance. This adapter doesn't support static linting +for adapted instance properties in a configuration document. + +Each name for each property must be a configurable property of the PSDSC resource. The property +name isn't case sensitive. The value for each property must be valid for that property. If you +specify an invalid property name or value, the adapter raises an error when it tries to invoke the +resource. + +```yaml +Type: object +Required: true +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Error + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed because the underlying DSC resource method or `Invoke-DscResource` call did not succeed. +When the resource returns this exit code, it also emits an error message with details about the failure. + + +[01]: ./examples/manage-a-windows-service.md +[02]: ../../../../schemas/config/type.md \ No newline at end of file From f72bc5dd5063243e1cae6553b89d7c6c10844c82 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 3 Jun 2025 07:12:45 +0200 Subject: [PATCH 07/13] Revert change on OSInfo --- .../resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml b/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml index 45d571104..4ab824969 100644 --- a/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml +++ b/docs/reference/resources/Microsoft/OSInfo/examples/osinfo.config.dsc.yaml @@ -9,4 +9,4 @@ resources: - name: Is64BitOS type: Microsoft/OSInfo properties: - bitness: '64' + bitness: '32' From 144828a21a336c8976a928a5b80e91a6124fc757 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 3 Jun 2025 07:19:28 +0200 Subject: [PATCH 08/13] Fix link definitions --- .../examples/check-for-pending-reboot.md | 1 - .../Microsoft/Windows/RebootPending/index.md | 23 +++++++++---------- 2 files changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md index ec4340bc4..cd83f8b65 100644 --- a/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md @@ -35,7 +35,6 @@ actualState: The `rebootPending` property indicates whether the system requires a reboot (`true`) or not (`false`). > [!NOTE] -> The `Microsoft.Windows/RebootPending` resource is read-only. > You can only use the **Get** operation to check the reboot status. > The resource does not support **Set**, **WhatIf**, **Export**, **Delete**, or **Test** operations. diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md index 665c68857..3e284ab54 100644 --- a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md @@ -64,14 +64,14 @@ This resource does not support `set`, `whatIf`, `export`, `test`, or `delete` op ## Examples -1. [Check for pending reboot][03] - Shows how to check if a system has a pending reboot using the `dsc resource get` command. -2. [Use the RebootPending resource in a configuration][04] - Shows how to include the RebootPending resource in a configuration document to check reboot status. +1. [Check for pending reboot][04] - Shows how to check if a system has a pending reboot using the `dsc resource get` command. +2. [Use the RebootPending resource in a configuration][05] - Shows how to include the RebootPending resource in a configuration document to check reboot status. ## Properties The resource doesn't have any configurable properties. It's a read-only resource designed to detect a system's reboot status. -- **Read-only properties:** The resource returns the following properties. For more information about read-only properties, see the "Read-only resource properties" section in [DSC resource properties][08]. +- **Read-only properties:** The resource returns the following properties. For more information about read-only properties, see the "Read-only resource properties" section in [DSC resource properties][03]. - [rebootPending](#rebootpending) - Indicates whether the system has a pending reboot. @@ -113,16 +113,15 @@ The resource doesn't return any specific exit codes. It reports status through t ## See also -- [Microsoft.Windows/Registry resource][10] -- [Windows Registry][11] +- [Microsoft.Windows/Registry resource][01] - [DSC resource capabilities][02] -- [DSC resource properties][06] +- [DSC resource properties][03] +- [Check for pending reboot][04] +- [Use the RebootPending resource in a configuration][05] +[01]: ../registry/index.md [02]: ../../../../../concepts/resources/capabilities.md -[03]: ./examples/check-for-pending-reboot.md -[04]: ./examples/use-rebootpending-in-configuration.md -[06]: ../../../../../concepts/resources/properties.md -[08]: ../../../../../concepts/resources/properties.md#read-only-resource-properties -[10]: ../registry/index.md -[11]: /windows/win32/sysinfo/about-the-registry +[03]: ../../../../../concepts/resources/properties.md +[04]: ./examples/check-for-pending-reboot.md +[05]: ./examples/use-rebootpending-in-configuration.md From da620cc8b376b7c1db39f044bf5465f0c5f2c7ca Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 3 Jun 2025 07:20:19 +0200 Subject: [PATCH 09/13] Format table --- .../resources/Microsoft/Windows/WindowsPowerShell/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md index 255239888..b84317386 100644 --- a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md +++ b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md @@ -61,8 +61,8 @@ discovery. If the cache doesn't exist during discovery, the adapter creates it. The location of the cache depends on your operating system. The following table defines the path for the Windows platform. -| Platform | Path | -| :------: | :----------------------------------------| +| Platform | Path | +| :------: | :---------------------------------------------- | | Windows | `%LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json` | The adapter versions the cache. The current version is `1`. If the version of the cache on a From d287999e9341f0508b7c9ccbc766585d84cb1154 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 3 Jun 2025 07:21:32 +0200 Subject: [PATCH 10/13] Clarification on script-based --- .../resources/Microsoft/Windows/WindowsPowerShell/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md index b84317386..e27e09fbb 100644 --- a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md +++ b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md @@ -198,13 +198,13 @@ The `type` property identifies the adapted instance's PSDSC Resource. The value must be the valid fully qualified type name for the resource. This adapter uses the following syntax for determining the fully qualified type name of a PSDSC -resource implemented as a PowerShell class: +resource implemented as a Windows PowerShell script-based: ```Syntax -/ +/ ``` -For example, if a PowerShell module named **TailspinToys** has a class-based PSDSC resource named +For example, if a PowerShell module named **TailspinToys** has a script-based PSDSC resource named `TSToy`, the fully qualified type name for that resource is `TailspinToys/TSToy`. For more information about type names in DSC, see From 2816d4d4ba347e0696d5789235e7444e0a9fc04a Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Thu, 5 Jun 2025 04:25:02 +0200 Subject: [PATCH 11/13] Add exit codes and rephrase sentence --- .../Microsoft/Windows/RebootPending/index.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md index 3e284ab54..24b7500f1 100644 --- a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md @@ -89,7 +89,8 @@ IsWriteOnly : false -A boolean value that indicates whether the system has a pending reboot. `true` if a reboot is pending; otherwise, `false`. +A boolean value that indicates whether the system has a pending reboot. This property is `true` if +a reboot is pending and otherwise `false`. ## Instance validating schema @@ -109,7 +110,18 @@ The following snippet contains the JSON Schema that validates an instance of the ## Exit codes -The resource doesn't return any specific exit codes. It reports status through the `rebootPending` property. +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Error + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed. ## See also From c013bdf49e75fdf2bdea064ced0782c65802e5bb Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Fri, 6 Jun 2025 15:09:27 +0200 Subject: [PATCH 12/13] Resolve remarks --- .../examples/check-for-pending-reboot.md | 14 +++++++++++--- .../Microsoft/Windows/RebootPending/index.md | 8 +++++++- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md index cd83f8b65..21ae050e2 100644 --- a/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md @@ -34,9 +34,17 @@ actualState: The `rebootPending` property indicates whether the system requires a reboot (`true`) or not (`false`). -> [!NOTE] -> You can only use the **Get** operation to check the reboot status. -> The resource does not support **Set**, **WhatIf**, **Export**, **Delete**, or **Test** operations. +> The resource doesn't implement the **Set**, **WhatIf**, **Export**, **Delete**, or **Test** +> capabilities. You can't use this resource to enforce or export configurations. +> +> Note that even though the resource doesn't implement **Test**, you can still invoke the test +> operation against the resource and use it in the `Microsoft.Dsc/Assertion` group resource. This +> resource relies on the synthetic testing provided by DSC. For more information about synthetic +> testing with DSC, see +> [DSC resource capabiltiies](../../../../../concepts/resources/capabilities.md#test). +> +> For an example using this resource in an assertion, see +> [Use the RebootPending resource in a configuration](./use-rebootpending-in-configuration.md). [01]: ../../../../../cli/resource/get.md \ No newline at end of file diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md index 24b7500f1..2afb6f471 100644 --- a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md @@ -60,7 +60,13 @@ The resource has the following capabilities: - `get` - You can use the resource to retrieve the pending reboot status of a system. -This resource does not support `set`, `whatIf`, `export`, `test`, or `delete` operations. For more information about resource capabilities, see [DSC resource capabilities][02]. +This resource doesn't implement the **Set**, **WhatIf**, **Export**, **Delete**, or **Test** +capabilities. You can't use this resource to enforce or export configurations. + +Note that even though this resource doesn't implement **Test**, you can still invoke the test +operation against this resource. This resource relies on the synthetic testing provided by DSC. + +For more information about resource capabilities, see [DSC resource capabilities][02]. ## Examples From 8130f87adc0852ca9256cc7e2d02e33c0b1c8812 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Sun, 8 Jun 2025 08:28:59 +0200 Subject: [PATCH 13/13] Add reasons --- .../Microsoft/Windows/RebootPending/index.md | 41 ++++++++++++++++--- 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md index 2afb6f471..c4b0142b2 100644 --- a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md @@ -98,19 +98,48 @@ IsWriteOnly : false A boolean value that indicates whether the system has a pending reboot. This property is `true` if a reboot is pending and otherwise `false`. +### Reason + +
Expand for reason property metadata + +```yaml +Type : array, null +IsRequired : false +IsKey : false +IsReadOnly : true +IsWriteOnly : false +``` + +
+ +An array of strings that provides detailed information about why a reboot is pending, or `null` if no reboot is pending. When a reboot is required, this property contains specific reasons such as: + +- Windows Updates requiring restart +- Component-Based Servicing operations +- Pending file rename operations +- Computer rename pending +- Domain join operations pending + ## Instance validating schema The following snippet contains the JSON Schema that validates an instance of the resource. ```json { -"type": "null", - "properties": { - "rebootPending": { - "type": "boolean", - "readOnly": true + "type": "object", + "properties": { + "rebootPending": { + "type": "boolean", + "readOnly": true + }, + "reasons": { + "type": [ + "array", + "null" + ], + "readOnly": true + } } - } } ```