diff --git a/docs/concepts/output-accessibility.md b/docs/concepts/output-accessibility.md index 946129666..e18510705 100644 --- a/docs/concepts/output-accessibility.md +++ b/docs/concepts/output-accessibility.md @@ -43,7 +43,7 @@ dsc resource list | ConvertFrom-Json | Out-GridView The following example shows how to display a list of DSC adapted resources in a GridView control. ```powershell -dsc resource list -a Microsoft.Windows/WindowsPowerShell | +dsc resource list -a Microsoft.Adapter/WindowsPowerShell | ConvertFrom-Json | Out-GridView ``` @@ -83,7 +83,7 @@ Each of the following commands improves the output in a different way: experience for screen readers. ```powershell -dsc resource list -a Microsoft.Windows/WindowsPowerShell | +dsc resource list -a Microsoft.Adapter/WindowsPowerShell | ConvertFrom-Json | Where-Object {$_.type -like "*process*" } | Select-Object -Property Type, Kind, Version | diff --git a/docs/concepts/resources/overview.md b/docs/concepts/resources/overview.md index d42f5fe77..4e8f5eaf8 100644 --- a/docs/concepts/resources/overview.md +++ b/docs/concepts/resources/overview.md @@ -29,7 +29,7 @@ DSC supports several kinds of resources: resource instances and processes them. Group resources can apply special handling to their nested resource instances, like changing the user the resources run as. - An _adapter resource_ is a group resource that enables the use of noncommand resources with DSC. - For example, the `Microsoft.DSC/PowerShell` and `Microsoft.Windows/WindowsPowerShell` adapter + For example, the `Microsoft.Adapter/PowerShell` and `Microsoft.Adapter/WindowsPowerShell` adapter resources enable the use of PowerShell DSC (PSDSC) resources in DSC, invoking the resources in PowerShell and Windows PowerShell respectively. diff --git a/docs/overview.md b/docs/overview.md index 5f43cbecb..e029ab0fb 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -53,13 +53,13 @@ DSC differs from PowerShell Desired State Configuration (PSDSC) in a few importa - DSC doesn't _depend_ on PowerShell, Windows PowerShell, or the [PSDesiredStateConfiguration][01] PowerShell module. DSC provides full compatibility with PSDSC resources through the - `Microsoft.DSC/PowerShell` and `Microsoft.Windows/WindowsPowerShell` _adapter resources_. + `Microsoft.Adapter/PowerShell` and `Microsoft.Adapter/WindowsPowerShell` _adapter resources_. - With the `Microsoft.DSC/PowerShell` adapter resource, you can use any PSDSC resource implemented + With the `Microsoft.Adapter/PowerShell` adapter resource, you can use any PSDSC resource implemented as a PowerShell class. The resource handles discovering, validating, and invoking PSDSC resources in PowerShell. The resource is included in the DSC install package for every platform. - With the `Microsoft.Windows/WindowsPowerShell` adapter resource, you can use any PSDSC resource + With the `Microsoft.Adapter/WindowsPowerShell` adapter resource, you can use any PSDSC resource compatible with Windows PowerShell. The resource handles discovering, validating, and invoking PSDSC resources in Windows PowerShell. The resource is included in the DSC install packages for Windows only. diff --git a/docs/reference/cli/resource/list.md b/docs/reference/cli/resource/list.md index 684a37acb..5a60c3db0 100644 --- a/docs/reference/cli/resource/list.md +++ b/docs/reference/cli/resource/list.md @@ -145,14 +145,14 @@ adds the returned list of adapted resources to the discovered resource list. DSC further filters specified with the command after this enumeration. ```sh -dsc resource list --adapter Microsoft.Windows/WindowsPowerShell +dsc resource list --adapter Microsoft.Adapter/WindowsPowerShell ``` This next command specifies the resource name filter `*Windows*`, limiting the list of returned resources: ```sh -dsc resource list --adapter Microsoft.Windows/WindowsPowerShell *Windows* +dsc resource list --adapter Microsoft.Adapter/WindowsPowerShell *Windows* ``` ## Arguments diff --git a/docs/reference/resources/Microsoft/Adapter/PowerShell/examples/configure-a-machine.md b/docs/reference/resources/Microsoft/Adapter/PowerShell/examples/configure-a-machine.md new file mode 100644 index 000000000..fc7a8904e --- /dev/null +++ b/docs/reference/resources/Microsoft/Adapter/PowerShell/examples/configure-a-machine.md @@ -0,0 +1,234 @@ +--- +description: > + Example showing how to configure a machine using multiple class-based PowerShell DSC resources + with the Microsoft.Adapter/PowerShell adapter in a DSC configuration document. + +ms.date: 03/23/2026 +ms.topic: reference +title: Configure a machine with the PowerShell adapter +--- + +# Configure a machine with the PowerShell adapter + +This example shows how to use the `Microsoft.Adapter/PowerShell` adapter to configure a machine +using multiple class-based PowerShell DSC resources in a single configuration document. These +examples use the `Microsoft.WinGet.DSC/WinGetPackage` resource from the **Microsoft.WinGet.DSC** +module to ensure several packages are installed. + +## Definition + +The following configuration document defines multiple `Microsoft.WinGet.DSC/WinGetPackage` +instances. + +Save the following YAML as `dev-tools.dsc.yaml`: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + ensureTools: + type: string + defaultValue: Present + allowedValues: + - Present + - Absent +resources: +- name: Windows Terminal + type: Microsoft.WinGet.DSC/WinGetPackage + properties: + Id: Microsoft.WindowsTerminal + Ensure: "[parameters('ensureTools')]" +- name: Visual Studio Code + type: Microsoft.WinGet.DSC/WinGetPackage + properties: + Id: Microsoft.VisualStudioCode + Ensure: "[parameters('ensureTools')]" +``` + +## Setup + +This example installs the WinGet software packages for the Windows Terminal and VS Code. The output +in this example shows the behavior when these packages aren't already installed on the system. + +This example depends on the **Microsoft.WinGet.DSC** PowerShell module at version `1.12.440`. To +install the module, open a PowerShell session and invoke the following command: + +```powershell +Install-PSResource -Name Microsoft.WinGet.DSC -Version 1.12.440 +``` + +> [!WARNING] +> Uninstalling and reinstalling software may have unintentional side effects related to how that +> software behaves, especially if uninstalling the software removes all previously defined +> configuration for it. + +To ensure that the packages aren't installed, invoke the following commands: + +```powershell +winget uninstall --id Microsoft.WindowsTerminal +winget uninstall --id Microsoft.VisualStudioCode +``` + +## Test the 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 dev-tools.dsc.yaml +``` + +DSC reports the results for each instance, showing which packages need to be installed. For this +example, neither package shows as installed: + +```yaml +executionInformation: + # Elided for brevity +metadata: + # Elided for brevity +results: +- executionInformation: + duration: PT8.0298239S + metadata: + Microsoft.DSC: + duration: PT8.0298239S + name: Windows Terminal + type: Microsoft.WinGet.DSC/WinGetPackage + result: + desiredState: + Id: Microsoft.WindowsTerminal + Ensure: Present + actualState: + Version: null + MatchOption: EqualsCaseInsensitive + UseLatest: false + InstallMode: Silent + Id: Microsoft.WindowsTerminal + Ensure: Absent + Source: '' + _inDesiredState: false + inDesiredState: false + differingProperties: + - Ensure +- executionInformation: + duration: PT7.6445836S + metadata: + Microsoft.DSC: + duration: PT7.6445836S + name: Visual Studio Code + type: Microsoft.WinGet.DSC/WinGetPackage + result: + desiredState: + Id: Microsoft.VisualStudioCode + Ensure: Present + actualState: + UseLatest: false + Version: null + Source: '' + Ensure: Absent + Id: Microsoft.VisualStudioCode + MatchOption: EqualsCaseInsensitive + InstallMode: Silent + _inDesiredState: false + inDesiredState: false + differingProperties: + - Ensure +messages: [] +hadErrors: false +``` + +## Apply the configuration + +Use the [`dsc config set`][02] command to install any packages that aren't already present: + +```powershell +dsc config set --file dev-tools.dsc.yaml +``` + +```yaml +executionInformation: + # Elided for brevity +metadata: + # Elided for brevity +results: +- executionInformation: + duration: PT34.4280028S + metadata: + Microsoft.DSC: + duration: PT34.4280028S + name: Windows Terminal + type: Microsoft.WinGet.DSC/WinGetPackage + result: + beforeState: + InstallMode: Silent + UseLatest: false + Source: '' + Id: Microsoft.WindowsTerminal + Ensure: Absent + Version: null + MatchOption: EqualsCaseInsensitive + afterState: + Version: 1.24.10921.0 + UseLatest: true + Source: winget + InstallMode: Silent + Ensure: Present + MatchOption: EqualsCaseInsensitive + Id: Microsoft.WindowsTerminal + changedProperties: + - Version + - UseLatest + - Source + - Ensure +- executionInformation: + duration: PT11.6464059S + metadata: + Microsoft.DSC: + duration: PT11.6464059S + name: Visual Studio Code + type: Microsoft.WinGet.DSC/WinGetPackage + result: + beforeState: + UseLatest: false + Ensure: Absent + Id: Microsoft.VisualStudioCode + MatchOption: EqualsCaseInsensitive + InstallMode: Silent + Source: '' + Version: null + afterState: + Id: Microsoft.VisualStudioCode + MatchOption: EqualsCaseInsensitive + Source: winget + Version: 1.119.0 + InstallMode: Silent + Ensure: Present + UseLatest: true + changedProperties: + - Source + - Version + - Ensure + - UseLatest +messages: [] +hadErrors: false +``` + +DSC installed both of the missing packages and reports that the state of each instance was changed +during the `set` operation. + +## Remove the packages + +To uninstall the packages, override the `ensureTools` parameter when applying the configuration: + +```powershell +$params = @{ + parameters = @{ + ensureTools = 'Absent' + } +} | ConvertTo-Json -Compress + +dsc config --parameters $params set --file dev-tools.dsc.yaml +``` + + +[01]: ../../../../../../cli/config/test.md +[02]: ../../../../../../cli/config/set.md diff --git a/docs/reference/resources/Microsoft/Adapter/PowerShell/examples/invoke-a-resource.md b/docs/reference/resources/Microsoft/Adapter/PowerShell/examples/invoke-a-resource.md new file mode 100644 index 000000000..b3a4439d3 --- /dev/null +++ b/docs/reference/resources/Microsoft/Adapter/PowerShell/examples/invoke-a-resource.md @@ -0,0 +1,168 @@ +--- +description: > + Example showing how to invoke a class-based PowerShell DSC resource using the + Microsoft.Adapter/PowerShell adapter. +ms.date: 03/23/2026 +ms.topic: reference +title: Invoke a resource with the PowerShell adapter +--- + +This example shows how to use the `Microsoft.Adapter/PowerShell` adapter to invoke a class-based +PowerShell DSC (PSDSC) resource. These examples use the `Microsoft.WinGet.DSC/WinGetPackage` resource from +the **Microsoft.WinGet.DSC** module to check whether Windows Terminal is installed. + +## Setup + +This example installs the WinGet software package for the Windows terminal. The output in this example shows the behavior when this package isn't already installed on the system. + +This example depends on the **Microsoft.WinGet.DSC** PowerShell module at version `1.12.440`. To install the module, open a PowerShell session and invoke the following command: + +```powershell +Install-PSResource -Name Microsoft.WinGet.DSC -Version 1.12.440 +``` + +> [!WARNING] +> Uninstalling and reinstalling software may have unintentional side effects related to how that +> software behaves, especially if uninstalling the software removes all previously defined +> configuration for it. + +To ensure that the packages aren't installed, invoke the following command: + +```powershell +winget uninstall --id Microsoft.WindowsTerminal +``` + +## Discover available adapted PSDSC resources + +To show available adapted PSDSC resources, use the [`dsc resource list`][01] command with the +[`--adapter`][02] option as `Microsoft.Adapter/PowerShell`: + +```powershell +dsc resource list --adapter Microsoft.Adapter/PowerShell +``` + +```console +Type Kind Version Capabilities RequireAdapter Description +-------------------------------------------------------------------------------------------------------------------------------------------- +Microsoft.PowerToys.Configure/PowerToysConfigure Resource 0.85.1 gs--t---- Microsoft.Adapter/PowerShell The module enabl… +Microsoft.Windows.Developer/AdvancedNetworkSharingSetting Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/DeveloperMode Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/EnableDarkMode Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/EnableLongPathSupport Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/EnableRemoteDesktop Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/FirewallRule Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/NetConnectionProfile Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/OsVersion Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/PowerPlanSetting Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/ShowSecondsInClock Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/Taskbar Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/UserAccessControl Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/WindowsCapability Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.Windows.Developer/WindowsExplorer Resource 0.4.0 gs--t---- Microsoft.Adapter/PowerShell DSC Resource for +Microsoft.WinGet.DSC/WinGetAdminSettings Resource 1.12.440 gs--t---- Microsoft.Adapter/PowerShell PowerShell Modul… +Microsoft.WinGet.DSC/WinGetPackage Resource 1.12.440 gs--t---- Microsoft.Adapter/PowerShell PowerShell Modul… +Microsoft.WinGet.DSC/WinGetPackageManager Resource 1.12.440 gs--t---- Microsoft.Adapter/PowerShell PowerShell Modul… +Microsoft.WinGet.DSC/WinGetSource Resource 1.12.440 gs--t---- Microsoft.Adapter/PowerShell PowerShell Modul… +Microsoft.WinGet.DSC/WinGetUserSettings Resource 1.12.440 gs--t---- Microsoft.Adapter/PowerShell PowerShell Modul… +``` + +## Test whether an instance is in the desired state + +You can use the [`dsc resource test`][03] command to invoke the `test` operation for a resource +without authoring a configuration document. + +The following snippet invokes the `Microsoft.WinGet.DSC/WinGetPackage` PSDSC resource to check +whether the Windows Terminal package is installed: + +```powershell +$resource = 'Microsoft.WinGet.DSC/WinGetPackage' +$instance = @{ + Id = 'Microsoft.WindowsTerminal' + Ensure = 'Present' +} | ConvertTo-Json -Compress + +dsc resource test --resource $resource --input $instance +``` + +When the package isn't installed, DSC returns the following result: + +```yaml +desiredState: + Id: Microsoft.WindowsTerminal + Ensure: Present +actualState: + Id: Microsoft.WindowsTerminal + InstallMode: Silent + Version: null + Ensure: Absent + MatchOption: EqualsCaseInsensitive + Source: '' + UseLatest: false + _inDesiredState: false +inDesiredState: false +differingProperties: +- Ensure +``` + +The `inDesiredState` field is `false` and `differingProperties` shows that `Ensure` differs between +the desired state and the actual state. + +## Set an instance to the desired state + +Use the [`dsc config set`][04] command to enforce the desired state for the resource instance: + +```powershell +$resource = 'Microsoft.WinGet.DSC/WinGetPackage' +$instance = @{ + Id = 'Microsoft.WindowsTerminal' + Ensure = 'Present' +} | ConvertTo-Json -Compress + +dsc resource set --resource $resource --input $instance +``` + +When the resource installs the package, DSC returns the following result: + +```yaml +beforeState: + Ensure: Absent + UseLatest: false + InstallMode: Silent + Version: null + Id: Microsoft.WindowsTerminal + MatchOption: EqualsCaseInsensitive + Source: '' +afterState: + Version: 1.24.10921.0 + MatchOption: EqualsCaseInsensitive + Ensure: Present + Id: Microsoft.WindowsTerminal + UseLatest: true + InstallMode: Silent + Source: winget +changedProperties: +- Version +- Ensure +- UseLatest +- Source +``` + +## Cleanup + +To remove the installed package, define the desired state for the `Ensure` property as `Absent` and invoke the `dsc resource set` command again: + +```powershell +$resource = 'Microsoft.WinGet.DSC/WinGetPackage' +$instance = @{ + Id = 'Microsoft.WindowsTerminal' + Ensure = 'Absent' +} | ConvertTo-Json -Compress + +dsc resource set --resource $resource --input $instance +``` + + +[01]: ../../../../../cli/resource/list.md +[02]: ../../../../../cli/resource/list.md#--adapter +[03]: ../../../../../cli/resource/test.md +[04]: ../../../../../cli/resource/set.md diff --git a/docs/reference/resources/Microsoft/Adapter/PowerShell/index.md b/docs/reference/resources/Microsoft/Adapter/PowerShell/index.md new file mode 100644 index 000000000..61533f7c3 --- /dev/null +++ b/docs/reference/resources/Microsoft/Adapter/PowerShell/index.md @@ -0,0 +1,201 @@ +--- +description: Microsoft.Adapter/PowerShell resource adapter reference documentation +ms.date: 03/23/2026 +ms.topic: reference +title: Microsoft.Adapter/PowerShell +--- + +# Microsoft.Adapter/PowerShell + +## Synopsis + +Adapter for resources implemented as PowerShell DSC classes. + +## Metadata + +```yaml +Version: 0.1.0 +Kind: adapter +Tags: [linux, windows, macos, pwsh, powershell] +Executable: pwsh +MinimumDSCVersion: 3.2.0 +``` + +## Adapted resource instance definition syntax + +### Implicitly required adapter syntax + +```yaml +- name: + type: / + properties: # adapted resource properties + : +``` + +### Explicitly required adapter syntax + +```yaml +- name: + type: / + properties: # adapted resource properties + : + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell +``` + +## Description + +The `Microsoft.Adapter/PowerShell` adapter resource enables you to use PowerShell Desired State +Configuration (PSDSC) resources in DSC. The adapter discovers and invokes PSDSC resources +implemented as PowerShell classes compatible with PowerShell. + +The adapter manages the PSDSC resources in PowerShell (`pwsh`), not Windows PowerShell (`powershell.exe`). To use +MOF-based PSDSC resources or PSDSC resources that require Windows PowerShell, use the +[Microsoft.Adapter/WindowsPowerShell][01] 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. + +> [!NOTE] +> This adapter replaces the deprecated [Microsoft.DSC/PowerShell][02] adapter. +> +> In earlier versions of DSC, adapted resources were nested inside a parent adapter resource using +> the `properties.resources` array. Starting in DSC 3.2, each adapted resource is listed directly +> in the configuration document's `resources` array. +> +> You can use the [`requireAdapter` directive][03] to explicitly indicate that the instance should +> use this adapter. When you don't specify the `requireAdapter` directive, DSC invokes the adapted +> resource through the first adapter that indicates it can invoke the resource. + +### PowerShell resource adapter cache + +The process for discovering the PowerShell resources available to the adapter can be +time-consuming. To improve performance, the adapter caches 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 each platform. + +| Platform | Path | +| :------: | :----------------------------------------| +| Linux | `$HOME/.dsc/PSAdapterCache.json` | +| macOS | `$HOME/.dsc/PSAdapterCache.json` | +| Windows | `%LOCALAPPDATA%\dsc\PSAdapterCache.json` | + +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: + +- 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.Adapter/PowerShell | + ConvertFrom-Json | + Select-Object -ExpandProperty directory | + Join-Path -ChildPath 'psDscAdapter\powershell.resource.ps1' + +& $adapterScript -Operation ClearCache +``` + +## Requirements + +- This adapter is available on Linux, macOS, and Windows systems. +- Using this adapter requires a supported version of PowerShell. + + DSC invokes the adapter as a + PowerShell script. For more information about installing PowerShell, see + [Install PowerShell on Windows, Linux, and macOS][04]. +- This adapter only supports PSDSC resources implemented as PowerShell classes. + + To use PSDSC resources in DSC that aren't defined as PowerShell classes, + use the [`Microsoft.Adapter/WindowsPowerShell`][01] adapter. + +## Capabilities + +The resource adapter has the following capabilities: + +- `get` - Retrieve the actual state of an adapted DSC resource instance. +- `set` - Enforce the desired state for an adapted DSC resource instance. +- `test` - Determine whether an adapted DSC resource instance is in the desired state. +- `export` - Discover and enumerate adapted DSC resource instances available on the system. +- `list` - List available Windows PowerShell DSC resources that can be used as adapted DSC + resources. + +## Examples + +- [Invoke a resource with the PowerShell adapter][05] +- [Configure a machine with the PowerShell adapter][06] + +## Adapted resource instances + +Define adapted resource instances directly in the configuration document's `resources` array. + +To explicitly indicate that DSC should use this adapter for the resource instance, define the +`requireAdapter` directive as `Microsoft.Adapter/PowerShell`. When you don't specify the +`requireAdapter` directive, DSC invokes the adapted resource through the first adapter that +indicates it can invoke the resource. + +Adapted resource instances are defined identically to non-adapted resource instances in a +configuration document with the following exceptions: + +1. The fully qualified type name (`type` field) for the adapted instance is defined by the adapter. + This adapter uses the following syntax for determining the fully qualified type name of a PSDSC + resource: + + ```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][07]. + +1. The `properties` field for the instance is 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 property name 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. + +## Exit codes + +The resource uses the following exit codes to report success and errors: + +- `0` - Success +- `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 didn't succeed. +When the adapter returns this exit code, it also emits an error message with details about the +failure. + +## See also + +- [Microsoft.Adapter/WindowsPowerShell][01] +- [Microsoft.DSC/PowerShell][02] (deprecated) + + +[01]: ../WindowsPowerShell/index.md +[02]: ../../DSC/PowerShell/index.md +[03]: ../../../../schemas/config/resource.md#requireAdapter +[04]: /powershell/scripting/install/installing-powershell +[05]: examples/invoke-a-resource.md +[06]: examples/configure-a-machine.md +[07]: ../../../../concepts/type-names.md diff --git a/docs/reference/resources/Microsoft/Adapter/WindowsPowerShell/examples/manage-a-windows-service.md b/docs/reference/resources/Microsoft/Adapter/WindowsPowerShell/examples/manage-a-windows-service.md new file mode 100644 index 000000000..9ef28c0b7 --- /dev/null +++ b/docs/reference/resources/Microsoft/Adapter/WindowsPowerShell/examples/manage-a-windows-service.md @@ -0,0 +1,310 @@ +--- +description: > + Example showing how to manage a Windows service using the PSDesiredStateConfiguration module + with the Microsoft.Adapter/WindowsPowerShell adapter in a DSC configuration document. + +ms.date: 03/23/2026 +ms.topic: reference +title: Manage a Windows service +--- + +# Manage a Windows service + +This example shows how to use the `Microsoft.Adapter/WindowsPowerShell` adapter with the +`PSDesiredStateConfiguration/Service` adapted PSDSC resource 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.2.0` or later. + +## Definition + +The following configuration document defines a single `PSDesiredStateConfiguration/Service` +instance. It expects the `Spooler` service to be set to startup automatically. + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +directives: + securityContext: elevated +resources: +- name: Spooler service + type: PSDesiredStateConfiguration/Service + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell + properties: + Name: Spooler + StartupType: Automatic +``` + +Copy the configuration document and save it as `spooler.dsc.yaml`. + +## Setup + +This example modifies the `Spooler` service. The example assumes that the service is currently +running and set to require manual startup. + +To put your system into the starting state for this example, run the following PowerShell command: + +```powershell +Get-Service Spooler | ForEach-Object -Process { + if ($_.StartType -ne 'Manual') { + $_ | Set-Service -StartupType Manual + } + if ($_.Status -ne 'Running') { + $_ | Start-Service + } +} + +Get-Service Spooler | Format-Table -Property Name, Status, StartType +``` + +You should get output from the final `Get-Service` command that shows the service is in the +expected state for the example: + +```console +Name Status StartType +---- ------ --------- +Spooler Running Manual +``` + +## Test whether a service is running + +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 spooler.dsc.yaml +``` + +When the service has a different startup type, DSC returns the following result: + +```yaml +executionInformation: + duration: PT424.3956473S + endDatetime: 2026-05-07T10:30:10.621622500-05:00 + executionType: actual + operation: test + securityContext: elevated + startDatetime: 2026-05-07T10:23:06.225975200-05:00 + version: 3.3.0-preview.1 +metadata: + Microsoft.DSC: + duration: PT424.395627S + endDatetime: 2026-05-07T10:30:10.621602200-05:00 + executionType: actual + operation: test + securityContext: elevated + startDatetime: 2026-05-07T10:23:06.225975200-05:00 + version: 3.3.0-preview.1 +results: +- executionInformation: + duration: PT95.7531029S + metadata: + Microsoft.DSC: + duration: PT95.7531029S + name: Spooler service + type: PSDesiredStateConfiguration/Service + result: + desiredState: + Name: Spooler + StartupType: Automatic + 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: Running + ModuleVersion: '1.1' + ModuleName: PSDesiredStateConfiguration + Path: C:\WINDOWS\System32\spoolsv.exe + Dependencies: + - RPCSS + - http + _inDesiredState: false + inDesiredState: false + differingProperties: + - StartupType +messages: [] +hadErrors: false +``` + +The `inDesiredState` field is `false` and `differingProperties` shows that `StartupType` differs. + +## Ensure a service is running with automatic startup + +Use the [`dsc config set`][02] command to configure the service: + +```powershell +dsc config set --file spooler.dsc.yaml +``` + +When the resource configures the service, DSC returns the following result: + +```yaml +executionInformation: + duration: PT282.1686621S + endDatetime: 2026-05-07T13:38:50.583007700-05:00 + executionType: actual + operation: set + securityContext: elevated + startDatetime: 2026-05-07T13:34:08.414345600-05:00 + version: 3.3.0-preview.1 +metadata: + Microsoft.DSC: + duration: PT282.1686429S + endDatetime: 2026-05-07T13:38:50.582988500-05:00 + executionType: actual + operation: set + securityContext: elevated + startDatetime: 2026-05-07T13:34:08.414345600-05:00 + version: 3.3.0-preview.1 +results: +- executionInformation: + duration: PT180.7721614S + metadata: + Microsoft.DSC: + duration: PT180.7721614S + name: Spooler service + type: PSDesiredStateConfiguration/Service + result: + 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 +messages: [] +hadErrors: false +``` + +Run the test again to confirm the service is now configured correctly: + +```powershell +dsc config test --file spooler.dsc.yaml +``` + +```yaml +executionInformation: + duration: PT188.0880439S + endDatetime: 2026-05-07T13:49:04.563267-05:00 + executionType: actual + operation: test + securityContext: elevated + startDatetime: 2026-05-07T13:45:56.475223100-05:00 + version: 3.3.0-preview.1 +metadata: + Microsoft.DSC: + duration: PT188.0880252S + endDatetime: 2026-05-07T13:49:04.563248300-05:00 + executionType: actual + operation: test + securityContext: elevated + startDatetime: 2026-05-07T13:45:56.475223100-05:00 + version: 3.3.0-preview.1 +results: +- executionInformation: + duration: PT94.8140892S + metadata: + Microsoft.DSC: + duration: PT94.8140892S + name: Spooler service + type: PSDesiredStateConfiguration/Service + result: + desiredState: + Name: Spooler + StartupType: Automatic + 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: Automatic + State: Running + ModuleVersion: '1.1' + ModuleName: PSDesiredStateConfiguration + Path: C:\WINDOWS\System32\spoolsv.exe + Dependencies: + - RPCSS + - http + _inDesiredState: true + inDesiredState: true + differingProperties: [] +messages: [] +hadErrors: false +``` + +## Cleanup + +To stop the service and set startup type to manual, use the [`dsc resource set`][03] command: + +```powershell +dsc resource set PSDesiredStateConfiguration/Service --input @' +Name: Spooler +State: Stopped +StartupType: Manual +'@ +``` + + +[01]: ../../../../../cli/config/test.md +[02]: ../../../../../cli/config/set.md +[03]: ../../../../../cli/resource/set.md diff --git a/docs/reference/resources/Microsoft/Adapter/WindowsPowerShell/index.md b/docs/reference/resources/Microsoft/Adapter/WindowsPowerShell/index.md new file mode 100644 index 000000000..e39bb81cb --- /dev/null +++ b/docs/reference/resources/Microsoft/Adapter/WindowsPowerShell/index.md @@ -0,0 +1,210 @@ +--- +description: Microsoft.Adapter/WindowsPowerShell resource adapter reference documentation +ms.date: 03/23/2026 +ms.topic: reference +title: Microsoft.Adapter/WindowsPowerShell +--- + +# Microsoft.Adapter/WindowsPowerShell + +## Synopsis + +Adapter for resources implemented as binary, script, or PowerShell classes in Windows PowerShell. + +## Metadata + +```yaml +Version: 0.1.0 +Kind: adapter +Tags: [windows, powershell] +Executable: powershell +MinimumDSCVersion: 3.2.0 +``` + +## Adapted resource instance definition syntax + +### Implicitly required adapter syntax + +```yaml +- name: + type: / + properties: # adapted resource properties + : +``` + +### Explicitly required adapter syntax + +```yaml +- name: + type: / + properties: # adapted resource properties + : + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell +``` + +## Description + +The `Microsoft.Adapter/WindowsPowerShell` adapter resource enables you to use PowerShell Desired +State Configuration (PSDSC) resources in DSC. The adapter discovers and invokes PSDSC resources +compatible with Windows PowerShell and PSDSC version `1.1`. + +The adapter manages the PSDSC resources in Windows PowerShell (powershell.exe), not PowerShell +(pwsh). To use class-based PSDSC resources in PowerShell, use the +[Microsoft.Adapter/PowerShell][01] 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`. + +> [!NOTE] +> This adapter replaces the deprecated [Microsoft.Windows/WindowsPowerShell][02] adapter. +> +> In earlier versions of DSC, adapted resources were nested inside a parent adapter resource using +> the `properties.resources` array. Starting in DSC 3.2, each adapted resource is listed directly +> in the configuration document's `resources` array. +> +> You can use the [`requireAdapter` directive][03] to explicitly indicate that the instance should +> use this adapter. When you don't specify the `requireAdapter` directive, DSC invokes the adapted +> resource through the first adapter that indicates it can invoke the resource. + +### Windows 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 following table defines the cache 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.Adapter/WindowsPowerShell | + ConvertFrom-Json | + Select-Object -ExpandProperty directory | + Join-Path -ChildPath 'psDscAdapter\powershell.resource.ps1' + +& $adapterScript -Operation ClearCache +``` + +## Requirements + +- This adapter is only available on Windows. +- The process security context must be elevated. + + For PSDSC 1.1, invoking DSC resources requires the process to run as Administrator. Attempting to + invoke the resources in a non-elevated context fails. +- Windows PowerShell Desired State Configuration (PSDSC) depends on WinRM. If WinRM isn't setup on + the machine, invoking PSDSC resources through the adapter will raise an error. + + You can use the [`Enable-PSRemoting` cmdlet][04] in an elevated Windows PowerShell session to + enable WinRM. +- PowerShell modules exposing PSDSC resources for use with this adapter must be installed in one of + the following locations: + + - `%PROGRAMFILES%\WindowsPowerShell\Modules` + - `%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules` + + PSDSC 1.1 only finds PSDSC resources when the module containing them is installed in the machine + scope. Modules containing PSDSC resources in the user scope or another non-default location + aren't recognized by PSDSC 1.1 and can't be invoked through this adapter. + +## Capabilities + +The resource adapter has the following capabilities: + +- `get` - Retrieve the actual state of an adapted DSC resource instance. +- `set` - Enforce the desired state for an adapted DSC resource instance. +- `test` - Determine whether an adapted DSC resource instance is in the desired state. +- `export` - Discover and enumerate adapted DSC resource instances available on the system. +- `list` - List available Windows PowerShell DSC resources that can be used as adapted DSC + resources. + +> [!NOTE] +> The `export` capability is only available for class-based PSDSC resources. Script-based and +> binary PSDSC resources don't support the export operation. + +## Examples + +- [Manage a Windows service with the WindowsPowerShell adapter][05] + +## Adapted resource instances + +Define adapted resource instances directly in the configuration document's `resources` array. + +To explicitly indicate that DSC should use this adapter for the resource instance, define the +`requireAdapter` directive as `Microsoft.Adapter/WindowsPowerShell`. When you don't specify the +`requireAdapter` directive, DSC invokes the adapted resource through the first adapter that +indicates it can invoke the resource. + +Adapted resource instances are defined identically to non-adapted resource instances in a +configuration document with the following exceptions: + +1. The fully qualified type name (`type` field) for the adapted instance is defined by the adapter. + This adapter uses the following syntax for determining the fully qualified type name of a PSDSC + resource: + + ```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][06]. + +1. The `properties` field for the instance is 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 property name 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. + +## Exit codes + +The adapter 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 didn't succeed. When the adapter returns this exit code, it also emits +an error message with details about the failure. + +## See also + +- [Microsoft.Adapter/PowerShell][01] +- [Microsoft.Windows/WindowsPowerShell][02] (deprecated) + + +[01]: ../PowerShell/index.md +[02]: ../../Windows/WindowsPowerShell/index.md +[03]: ../../../../schemas/config/resource.md#requireAdapter +[04]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/enable-psremoting?view=powershell-5.1&preserveView=true +[05]: examples/manage-a-windows-service.md +[06]: ../../../../schemas/definitions/resourceType.md diff --git a/docs/reference/resources/overview.md b/docs/reference/resources/overview.md index 050999f1b..7e3e7e5eb 100644 --- a/docs/reference/resources/overview.md +++ b/docs/reference/resources/overview.md @@ -9,6 +9,8 @@ This document lists the available resources and links to the reference documenta - [Microsoft.DSC/Assertion](./microsoft/dsc/assertion/resource.md) - [Microsoft.DSC/Group](./microsoft/dsc/group/resource.md) - [Microsoft.DSC/Include](./microsoft/dsc/include/resource.md) +- [Microsoft.Adapter/PowerShell](./microsoft/adapter/powershell/index.md) +- [Microsoft.Adapter/WindowsPowerShell](./microsoft/adapter/windowspowershell/index.md) - [Microsoft.DSC/PowerShell](./microsoft/dsc/powershell/resource.md) - [Microsoft.DSC.Debug/Echo](./microsoft/dsc/debug/echo/resource.md) - [Microsoft.DSC.Transitional/RunCommandOnSet](./microsoft/dsc/transitional/runcomandonset/resource.md) @@ -31,10 +33,17 @@ change the state of the machine directly: You can use the following built-in resources to leverage resources that don't define a DSC Resource Manifest: -- [Microsoft.DSC/PowerShell](./microsoft/dsc/powershell/resource.md) -- [Microsoft.Windows/WindowsPowerSHell](./microsoft/windows/windowspowershell/resource.md) +- [Microsoft.Adapter/PowerShell](./microsoft/adapter/powershell/index.md) +- [Microsoft.Adapter/WindowsPowerShell](./microsoft/adapter/windowspowershell/index.md) +- [Microsoft.DSC/PowerShell](./microsoft/dsc/powershell/index.md) +- [Microsoft.Windows/WindowsPowerShell](./microsoft/windows/windowspowershell/index.md) - [Microsoft.Windows/WMI](./microsoft/windows/wmi/resource.md) +> [!WARNING] +> `Microsoft.DSC/PowerShell` and `Microsoft.Windows/WindowsPowerShell` will be deprecated in a +> future release. Use `Microsoft.Adapter/PowerShell` and `Microsoft.Adapter/WindowsPowerShell` +> instead. + ## Built-in configurable resources The following built-in resources to change the state of a machine directly: diff --git a/dsc/examples/multiline.dsc.yaml b/dsc/examples/multiline.dsc.yaml index 41122ee95..aa2cb78d5 100644 --- a/dsc/examples/multiline.dsc.yaml +++ b/dsc/examples/multiline.dsc.yaml @@ -1,13 +1,13 @@ $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: -- name: test multi-line +- name: test multiline type: Microsoft.DSC.Debug/Echo properties: output: | This is a 'multi-line' string. -- name: test single-quote escaping +- name: test single quote escaping type: Microsoft.DSC.Debug/Echo properties: output: "[concat('This is a single-quote: ', '''')]" diff --git a/dsc/examples/parallel.dsc.yaml b/dsc/examples/parallel.dsc.yaml deleted file mode 100644 index b88ea83bc..000000000 --- a/dsc/examples/parallel.dsc.yaml +++ /dev/null @@ -1,47 +0,0 @@ -# Example on how concurrency would be defined in the configuration. -$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json -metadata: - _timeoutSeconds: 600 # example of setting timeout for orchestration, should be namespaced? -resources: -- name: myParallelGroup - type: DSC/ParallelGroup # each resource in this group would run in parallel - properties: - resources: - - name: os - type: Microsoft/OSInfo - properties: {} - - name: windows product name - type: Microsoft.Windows/Registry - properties: - keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion - valueName: ProductName - - name: system root - type: Microsoft.Windows/Registry - properties: - keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion - valueName: SystemRoot -- name: myGroup - type: Microsoft.DSC/Group # each resource in this group would run in sequence - properties: - resources: - - name: current user registry - type: Microsoft.Windows/Registry - properties: - keyPath: HKCU\example - _ensure: present - - name: current user registry 2 - type: Microsoft.Windows/Registry - properties: - keyPath: HKCU\example2 - _ensure: present - - name: mygroup - type: Microsoft.DSC/Group - properties: - resources: - - name: myreg - type: Microsoft.Windows.Registry - properties: - keyPath: HKCU\example2 - _ensure: absent - dependsOn: - - '[DSC/ParallelGroup]myParallelGroup' diff --git a/dsc/examples/timezone.dsc.yaml b/dsc/examples/timezone.dsc.yaml index b09fdf137..3e21074d2 100644 --- a/dsc/examples/timezone.dsc.yaml +++ b/dsc/examples/timezone.dsc.yaml @@ -1,14 +1,10 @@ # Provides an example of a DSC configuration that uses a PowerShell DSC Resource not contained in PsDesiredStateConfiguration. # You must install the ComputerManagementDsc module to use this configuration -$schema: https://aka.ms/dsc/schemas/v3.0.0/bundled/config/document.json +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - - type: Microsoft.Windows/WindowsPowerShell + - type: ComputerManagementDsc/TimeZone name: Set Timezone properties: - resources: - - name: Set Timezone - type: ComputerManagementDsc/TimeZone - properties: - IsSingleInstance: Yes - TimeZone: New Zealand Standard Time + IsSingleInstance: Yes + TimeZone: New Zealand Standard Time diff --git a/dsc/examples/winget.dsc.yaml b/dsc/examples/winget.dsc.yaml index 8e3357e7f..1afdf0801 100644 --- a/dsc/examples/winget.dsc.yaml +++ b/dsc/examples/winget.dsc.yaml @@ -1,4 +1,4 @@ -# The `Microsoft.Winget.DSC` resources needs to be installed: install-psresource Microsoft.Winget.DSC -Prerelease +# The `Microsoft.Winget.DSC` resources needs to be installed: Install-PSResource Microsoft.Winget.DSC $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json parameters: @@ -9,16 +9,12 @@ parameters: - Present - Absent resources: -- name: Use class PowerShell resources - type: Microsoft.DSC/PowerShell +- name: PowerShell 7 Preview + type: Microsoft.WinGet.DSC/WinGetPackage properties: - resources: - - name: PowerShell 7 Preview - type: Microsoft.WinGet.DSC/WinGetPackage - properties: - Id: Microsoft.PowerShell.Preview - - name: Calc from Windows Store - type: Microsoft.WinGet.DSC/WinGetPackage - properties: - Id: "9WZDNCRFHVN5" - Ensure: "[parameters('ensureCalc')]" + Id: Microsoft.PowerShell.Preview +- name: Calc from Windows Store + type: Microsoft.WinGet.DSC/WinGetPackage + properties: + Id: "9WZDNCRFHVN5" + Ensure: "[parameters('ensureCalc')]" diff --git a/dsc/examples/winps_script.dsc.yaml b/dsc/examples/winps_script.dsc.yaml index 34a34359a..dadea989b 100644 --- a/dsc/examples/winps_script.dsc.yaml +++ b/dsc/examples/winps_script.dsc.yaml @@ -3,23 +3,19 @@ metadata: Microsoft.DSC: securityContext: elevated resources: - - type: Microsoft.Windows/WindowsPowerShell + - type: PSDesiredStateConfiguration/Script name: Run WinPS script - properties: - resources: - - name: Run script - type: PSDesiredStateConfiguration/Script - properties: - GetScript: | - $text = @" - get - "@ - # Returning result must be this type of hashtable - @{Result=$text} - TestScript: | - # TestScript must return a boolean - $true - SetScript: | - $text = @" - set - "@ + properties: + GetScript: | + $text = @" + get + "@ + # Returning result must be this type of hashtable + @{Result=$text} + TestScript: | + # TestScript must return a boolean + $true + SetScript: | + $text = @" + set + "@