docs: Add reference documentation for Microsoft.Adapter/PowerShell and Microsoft.Adapter/WindowsPowerShell#1444
docs: Add reference documentation for Microsoft.Adapter/PowerShell and Microsoft.Adapter/WindowsPowerShell#1444Gijsreyn wants to merge 2 commits intoPowerShell:mainfrom
Microsoft.Adapter/PowerShell and Microsoft.Adapter/WindowsPowerShell#1444Conversation
There was a problem hiding this comment.
Pull request overview
Adds new reference documentation for the DSC 3.2+ adapter resources Microsoft.Adapter/PowerShell and Microsoft.Adapter/WindowsPowerShell, and updates several docs/examples to use the directives.requireAdapter syntax instead of the older nested adapter pattern.
Changes:
- Added new reference pages + examples for the two new adapter resources.
- Migrated multiple example configuration documents to
directives.requireAdapter. - Updated CLI/docs references to point to the new adapter type names and marked older adapters as deprecated.
Reviewed changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| dsc/examples/winps_script.dsc.yaml | Migrates the Windows PowerShell script example to directives.requireAdapter. |
| dsc/examples/winget.dsc.yaml | Migrates WinGet example instances to directives.requireAdapter. |
| dsc/examples/timezone.dsc.yaml | Migrates TimeZone example to directives.requireAdapter. |
| dsc/examples/parallel.dsc.yaml | Removes the parallel/groups example config file. |
| dsc/examples/multiline.dsc.yaml | Updates instance names to comply with the instance name schema. |
| dsc/examples/groups.dsc.yaml | Updates config metadata key name for security context. |
| docs/reference/resources/overview.md | Adds the new adapters to the resource overview and includes a deprecation warning for old adapters. |
| docs/reference/resources/Microsoft/adapter/powershell/index.md | New reference doc for Microsoft.Adapter/PowerShell. |
| docs/reference/resources/Microsoft/adapter/powershell/examples/invoke-a-resource.md | New example showing usage of the PowerShell adapter. |
| docs/reference/resources/Microsoft/adapter/powershell/examples/configure-a-machine.md | New multi-resource example using the PowerShell adapter. |
| docs/reference/resources/Microsoft/adapter/windowspowershell/index.md | New reference doc for Microsoft.Adapter/WindowsPowerShell. |
| docs/reference/resources/Microsoft/adapter/windowspowershell/examples/manage-a-windows-service.md | New example showing usage of the Windows PowerShell adapter. |
| docs/reference/cli/resource/list.md | Updates dsc resource list --adapter examples to the new adapter name. |
| docs/overview.md | Updates overview text to reference the new adapter resources. |
| docs/get-started/index.md | Deleted in this PR (per diff). |
| docs/concepts/resources/overview.md | Updates adapter resource naming in concepts doc. |
| docs/concepts/output-accessibility.md | Updates adapter name in PowerShell examples. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - [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) |
There was a problem hiding this comment.
The links added here use the path prefix ./microsoft/..., but the repo’s directory is docs/reference/resources/Microsoft/... (capital M). On case-sensitive filesystems/site builds these links will be broken. Update these links (and the rest of this page) to match the actual on-disk casing and folder structure (for example ./Microsoft/adapter/powershell/index.md).
|
|
||
| ```powershell | ||
| $adapterScript = dsc resource list -a Microsoft.Adapter/PowerShell | | ||
| ConvertFrom-Json | | ||
| Select-Object -ExpandProperty directory | | ||
| Join-Path -ChildPath 'psDscAdapter' -AdditionalChildPath 'powershell.resource.ps1' | ||
|
|
||
| & $adapterScript -Operation ClearCache |
There was a problem hiding this comment.
The command used to locate the adapter script uses dsc resource list -a Microsoft.Adapter/PowerShell. Per the CLI docs, --adapter/-a switches the command into “list adapted resources” mode (and suppresses non-adapted resources), so it won’t reliably return the adapter resource’s directory. Use dsc resource list Microsoft.Adapter/PowerShell (no -a/--adapter) to get the adapter’s manifest info, consistent with the existing adapter docs.
| - 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 |
There was a problem hiding this comment.
PR description says docs/get-started/index.md was updated, but in this PR it appears to be removed entirely. If the deletion is intentional, the PR description should be updated; otherwise, the file likely needs to be restored/updated instead of deleted.
| 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) |
There was a problem hiding this comment.
These links also use the ./microsoft/... prefix and don’t match the actual path casing/layout under docs/reference/resources/Microsoft/... (and several targets are index.md in the repo, not resource.md). Update the link targets to the correct on-disk paths so they resolve in case-sensitive builds.
PR Summary
Adds reference documentation for the two new DSC 3.2 adapter resources and updates existing examples and docs to use the new
directives.requireAdaptersyntax.New documentation:
docs/reference/resources/microsoft/adapter/powershell/index.md— Reference doc forMicrosoft.Adapter/PowerShelldocs/reference/resources/microsoft/adapter/powershell/examples/invoke-a-resource.mddocs/reference/resources/microsoft/adapter/powershell/examples/configure-a-machine.mddocs/reference/resources/microsoft/adapter/windowspowershell/index.md— Reference doc forMicrosoft.Adapter/WindowsPowerShelldocs/reference/resources/microsoft/adapter/windowspowershell/examples/manage-a-windows-service.mdUpdated files
docs/reference/resources/overview.md— Added new adapters to the all-resources and adapter sections; added deprecation warning forMicrosoft.DSC/PowerShellandMicrosoft.Windows/WindowsPowerShelldocs/get-started/index.md— Updated YAML snippet to use new adapter syntaxdsc/examples/winget.dsc.yaml,winps_script.dsc.yaml,timezone.dsc.yaml— Migrated from old nested adapter pattern todirectives.requireAdapterdsc/examples/multiline.dsc.yaml— Fixed instance names to comply with^[a-zA-Z0-9 ]+$schemaNotes
directives.requireAdaptersyntax requires DSC 3.2.0 or later, noted throughout the new docs (preperation for GA release)Microsoft.DSC/PowerShell,Microsoft.Windows/WindowsPowerShell) are marked as deprecated with links to the new replacements