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/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..21ae050e2 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md @@ -0,0 +1,50 @@ +--- +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`). + +> 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/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..c4b0142b2 100644 --- a/docs/reference/resources/Microsoft/Windows/RebootPending/index.md +++ b/docs/reference/resources/Microsoft/Windows/RebootPending/index.md @@ -0,0 +1,174 @@ +--- +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 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 + +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][03]. + + - [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. 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": "object", + "properties": { + "rebootPending": { + "type": "boolean", + "readOnly": true + }, + "reasons": { + "type": [ + "array", + "null" + ], + "readOnly": 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. + +## See also + +- [Microsoft.Windows/Registry resource][01] +- [DSC resource capabilities][02] +- [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]: ../../../../../concepts/resources/properties.md +[04]: ./examples/check-for-pending-reboot.md +[05]: ./examples/use-rebootpending-in-configuration.md 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..e27e09fbb 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 Windows PowerShell script-based: + +```Syntax +/ +``` + +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 +[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