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..8d0fca2a3 --- /dev/null +++ b/docs/reference/resources/Microsoft/adapter/powershell/examples/configure-a-machine.md @@ -0,0 +1,89 @@ +--- +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 +--- + +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. + +> [!NOTE] +> Run this example with `dsc.exe` version 3.2.0 or later and the **Microsoft.WinGet.DSC** +> PowerShell module installed. Install the module with: +> `Install-PSResource Microsoft.WinGet.DSC` + +## Configuration document + +The following configuration document defines multiple `Microsoft.WinGet.DSC/WinGetPackage` +instances. Each instance sets `directives.requireAdapter` to `Microsoft.Adapter/PowerShell`. + +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: PowerShell 7 + type: Microsoft.WinGet.DSC/WinGetPackage + directives: + requireAdapter: Microsoft.Adapter/PowerShell + properties: + Id: Microsoft.PowerShell + Ensure: "[parameters('ensureTools')]" +- name: Windows Terminal + type: Microsoft.WinGet.DSC/WinGetPackage + directives: + requireAdapter: Microsoft.Adapter/PowerShell + properties: + Id: Microsoft.WindowsTerminal + Ensure: "[parameters('ensureTools')]" +- name: Visual Studio Code + type: Microsoft.WinGet.DSC/WinGetPackage + directives: + requireAdapter: Microsoft.Adapter/PowerShell + properties: + Id: Microsoft.VisualStudioCode + Ensure: "[parameters('ensureTools')]" +``` + +## Test the configuration + +Run the configuration test to check whether the packages are installed: + +```powershell +dsc config test --file dev-tools.dsc.yaml +``` + +DSC reports the results for each instance, showing which packages need to be installed. + +## Apply the configuration + +Run the configuration set to install any packages that aren't already present: + +```powershell +dsc config set --file dev-tools.dsc.yaml +``` + +## Remove the packages + +To uninstall the packages, override the `ensureTools` parameter when applying the configuration: + +```powershell +dsc config set --file dev-tools.dsc.yaml --parameters '{"ensureTools": "Absent"}' +``` + + +[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..0e52a7474 --- /dev/null +++ b/docs/reference/resources/Microsoft/adapter/powershell/examples/invoke-a-resource.md @@ -0,0 +1,117 @@ +--- +description: > + Example showing how to invoke a class-based PowerShell DSC resource using + Microsoft.Adapter/PowerShell in a DSC configuration document. +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 resource. These examples use the `Microsoft.WinGet.DSC/WinGetPackage` resource from +the **Microsoft.WinGet.DSC** module to check whether Windows Terminal is installed. + +> [!NOTE] +> Run this example with `dsc.exe` version 3.2.0 or later and the **Microsoft.WinGet.DSC** +> PowerShell module installed. Install the module with: +> `Install-PSResource Microsoft.WinGet.DSC` + +## Test whether a WinGet package is installed + +The following configuration document defines a single `Microsoft.WinGet.DSC/WinGetPackage` +instance that uses `directives.requireAdapter` to route the resource through the +`Microsoft.Adapter/PowerShell` adapter. + +Save the following YAML as `winget-test.dsc.yaml`: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Windows Terminal + type: Microsoft.WinGet.DSC/WinGetPackage + directives: + requireAdapter: Microsoft.Adapter/PowerShell + properties: + Id: Microsoft.WindowsTerminal + Ensure: Present +``` + +Run the configuration test operation to check whether Windows Terminal is installed: + +```powershell +dsc config test --file winget-test.dsc.yaml +``` + +When the package isn't installed, DSC returns the following result: + +```yaml +metadata: + Microsoft.DSC: + version: 3.2.0 + operation: test + executionType: actual + startDatetime: '2026-03-23T00:00:00.000000000+00:00' + endDatetime: '2026-03-23T00:00:01.000000000+00:00' + duration: PT1S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT0.5S + name: Windows Terminal + type: Microsoft.WinGet.DSC/WinGetPackage + result: + desiredState: + Id: Microsoft.WindowsTerminal + Ensure: Present + actualState: + Id: Microsoft.WindowsTerminal + Ensure: Absent + inDesiredState: false + differingProperties: + - Ensure +messages: [] +hadErrors: false +``` + +The `inDesiredState` field is `false` and `differingProperties` shows that `Ensure` differs between +the desired state and the actual state. + +## Install a WinGet package + +Use the `dsc config set` command to configure the system to the desired state: + +```powershell +dsc config set --file winget-test.dsc.yaml +``` + +When the resource installs the package, DSC returns the following result: + +```yaml +metadata: + Microsoft.DSC: + version: 3.2.0 + operation: set + executionType: actual + startDatetime: '2026-03-23T00:00:00.000000000+00:00' + endDatetime: '2026-03-23T00:00:05.000000000+00:00' + duration: PT5S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT4S + name: Windows Terminal + type: Microsoft.WinGet.DSC/WinGetPackage + result: + beforeState: + Id: Microsoft.WindowsTerminal + Ensure: Absent + afterState: + Id: Microsoft.WindowsTerminal + Ensure: Present + changedProperties: + - Ensure +messages: [] +hadErrors: false +``` 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..0eeeb5d4a --- /dev/null +++ b/docs/reference/resources/Microsoft/adapter/powershell/index.md @@ -0,0 +1,187 @@ +--- +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 +``` + +## Instance definition syntax + +> [!NOTE] +> The `directives.requireAdapter` syntax is available in DSC 3.2 and later. + +```yaml +resources: +- name: + type: / + directives: + requireAdapter: Microsoft.Adapter/PowerShell + properties: # adapted resource properties +``` + +## 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. + +The adapter manages the PSDSC resources in PowerShell (pwsh), not Windows PowerShell. To use +MOF-based PSDSC resources or PSDSC resources that require Windows PowerShell, use the +[Microsoft.Adapter/WindowsPowerShell](../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. + +> [!NOTE] +> This adapter replaces the deprecated [Microsoft.DSC/PowerShell](../../DSC/PowerShell/index.md) +> 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 with `directives.requireAdapter` +> set to `Microsoft.Adapter/PowerShell`. + +### 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' -AdditionalChildPath 'powershell.resource.ps1' + +& $adapterScript -Operation ClearCache +``` + +## Requirements + +- 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](/powershell/scripting/install/installing-powershell). + +## Examples + +- [Invoke a resource with the PowerShell adapter][02] +- [Configure a machine with the PowerShell adapter][03] + +## Adapted resource instances + +Adapted resource instances are listed directly in the configuration document's `resources` array. +Set `directives.requireAdapter` to `Microsoft.Adapter/PowerShell` to indicate that DSC should use +this adapter to invoke the instance. This feature requires DSC 3.2 or later. + +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 must be unique within the configuration document's `resources` array. + +```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][01]. + +```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 uses the following exit codes to report success and errors: + +- `0` - Success +- `1` - Error + +## See also + +- [Microsoft.Adapter/WindowsPowerShell](../windowspowershell/index.md) +- [Microsoft.DSC/PowerShell](../../DSC/PowerShell/index.md) (deprecated) + + +[01]: ../../../../concepts/type-names.md +[02]: examples/invoke-a-resource.md +[03]: examples/configure-a-machine.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..9e00bef2d --- /dev/null +++ b/docs/reference/resources/Microsoft/adapter/windowspowershell/examples/manage-a-windows-service.md @@ -0,0 +1,161 @@ +--- +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 +--- + +This example shows how to use the `Microsoft.Adapter/WindowsPowerShell` adapter with the +`PSDesiredStateConfiguration/Service` 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. + +## Test whether a service is running + +The following configuration document defines a single `PSDesiredStateConfiguration/Service` +instance that uses `directives.requireAdapter` to route the resource through the +`Microsoft.Adapter/WindowsPowerShell` adapter. + +Save the following YAML as `spooler.dsc.yaml`: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +metadata: + Microsoft.DSC: + securityContext: elevated +resources: +- name: Spooler service + type: PSDesiredStateConfiguration/Service + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell + properties: + Name: Spooler + StartupType: Automatic +``` + +Run the configuration test to check whether the service has the desired startup type: + +```powershell +dsc config test --file spooler.dsc.yaml +``` + +When the service has a different startup type, DSC returns the following result: + +```yaml +metadata: + Microsoft.DSC: + version: 3.2.0 + operation: test + executionType: actual + startDatetime: '2026-03-23T00:00:00.000000000+00:00' + endDatetime: '2026-03-23T00:00:01.000000000+00:00' + duration: PT1S + securityContext: elevated +results: +- metadata: + Microsoft.DSC: + duration: PT0.5S + name: Spooler service + type: PSDesiredStateConfiguration/Service + result: + desiredState: + Name: Spooler + StartupType: Automatic + actualState: + 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` 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 +metadata: + Microsoft.DSC: + version: 3.2.0 + operation: set + executionType: actual + startDatetime: '2026-03-23T00:00:00.000000000+00:00' + endDatetime: '2026-03-23T00:00:02.000000000+00:00' + duration: PT2S + securityContext: elevated +results: +- metadata: + Microsoft.DSC: + duration: PT1S + name: Spooler service + type: PSDesiredStateConfiguration/Service + result: + beforeState: + Name: Spooler + StartupType: Manual + State: Running + afterState: + Name: Spooler + StartupType: Automatic + State: Running + 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 +results: +- name: Spooler service + type: PSDesiredStateConfiguration/Service + result: + desiredState: + Name: Spooler + StartupType: Automatic + actualState: + InDesiredState: true + inDesiredState: true + differingProperties: [] +``` + +## Stop a service + +To stop the service and set startup type to manual, update the configuration document: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +metadata: + Microsoft.DSC: + securityContext: elevated +resources: +- name: Spooler service stopped + type: PSDesiredStateConfiguration/Service + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell + properties: + Name: Spooler + State: Stopped + StartupType: Manual +``` + +Apply the configuration with `dsc config set` to stop the service. 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..9ec0bcba1 --- /dev/null +++ b/docs/reference/resources/Microsoft/adapter/windowspowershell/index.md @@ -0,0 +1,211 @@ +--- +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 +``` + +## Instance definition syntax + +> [!NOTE] +> The `directives.requireAdapter` syntax is available in DSC 3.2 and later. + +```yaml +resources: +- name: + type: / + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell + properties: # adapted resource properties +``` + +## Description + +The `Microsoft.Adapter/WindowsPowerShell` adapter resource enables you to use PowerShell Desired +State Configuration (PSDSC) resources in DSC. The resource can: + +- Execute script-based DSC resources +- Run class-based DSC resource methods +- Execute binary DSC resources + +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](../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`. + +> [!NOTE] +> This adapter replaces the deprecated +> [Microsoft.Windows/WindowsPowerShell](../../Windows/WindowsPowerShell/index.md) 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 with `directives.requireAdapter` set to +> `Microsoft.Adapter/WindowsPowerShell`. + +### 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 context must have appropriate permissions for the DSC resources to be executed. +- PowerShell modules exposing DSC resources should be installed in one of the following locations: + - `%PROGRAMFILES%\WindowsPowerShell\Modules` + - `%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules` + +## Capabilities + +The resource adapter has the following capabilities: + +- `get` - Retrieve the actual state of a DSC resource instance. +- `set` - Enforce the desired state for a DSC resource instance. +- `test` - Determine whether a DSC resource instance is in the desired state. +- `export` - Discover and enumerate DSC resource instances available on the system. +- `list` - List available Windows PowerShell DSC resources 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 don't support the export operation. + +## Examples + +- [Manage a Windows service with the WindowsPowerShell adapter][02] + +## Adapted resource instances + +Adapted resource instances are listed directly in the configuration document's `resources` array. +Set `directives.requireAdapter` to `Microsoft.Adapter/WindowsPowerShell` to indicate that DSC +should use this adapter to invoke the instance. This feature requires DSC 3.2 or later. + +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 must be unique within the configuration document's `resources` array. + +```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: + +```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][01]. + +```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. + +## See also + +- [Microsoft.Adapter/PowerShell](../powershell/index.md) +- [Microsoft.Windows/WindowsPowerShell](../../Windows/WindowsPowerShell/index.md) (deprecated) + + +[01]: ../../../../concepts/type-names.md +[02]: examples/manage-a-windows-service.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/groups.dsc.yaml b/dsc/examples/groups.dsc.yaml index 0e5d2085e..a2ab9c107 100644 --- a/dsc/examples/groups.dsc.yaml +++ b/dsc/examples/groups.dsc.yaml @@ -38,4 +38,4 @@ resources: - name: Nested First type: Microsoft.DSC.Debug/Echo properties: - output: Nested First + output: Nested First \ No newline at end of file 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..40ee0946e 100644 --- a/dsc/examples/timezone.dsc.yaml +++ b/dsc/examples/timezone.dsc.yaml @@ -3,12 +3,10 @@ $schema: https://aka.ms/dsc/schemas/v3.0.0/bundled/config/document.json resources: - - type: Microsoft.Windows/WindowsPowerShell + - type: ComputerManagementDsc/TimeZone name: Set Timezone + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell 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..40f93a5e7 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,16 @@ parameters: - Present - Absent resources: -- name: Use class PowerShell resources - type: Microsoft.DSC/PowerShell +- name: PowerShell 7 Preview + type: Microsoft.WinGet.DSC/WinGetPackage + directives: + requireAdapter: Microsoft.Adapter/PowerShell 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 + directives: + requireAdapter: Microsoft.Adapter/PowerShell + properties: + Id: "9WZDNCRFHVN5" + Ensure: "[parameters('ensureCalc')]" diff --git a/dsc/examples/winps_script.dsc.yaml b/dsc/examples/winps_script.dsc.yaml index 34a34359a..1b6147838 100644 --- a/dsc/examples/winps_script.dsc.yaml +++ b/dsc/examples/winps_script.dsc.yaml @@ -3,23 +3,21 @@ 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 - "@ + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell + properties: + GetScript: | + $text = @" + get + "@ + # Returning result must be this type of hashtable + @{Result=$text} + TestScript: | + # TestScript must return a boolean + $true + SetScript: | + $text = @" + set + "@