Skip to content

Commit c611669

Browse files
GijsreynGijsreyn
committed
Update adapter docs
1 parent b8ccc7d commit c611669

17 files changed

Lines changed: 822 additions & 641 deletions

File tree

‎docs/concepts/output-accessibility.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ dsc resource list | ConvertFrom-Json | Out-GridView
4343
The following example shows how to display a list of DSC adapted resources in a GridView control.
4444

4545
```powershell
46-
dsc resource list -a Microsoft.Windows/WindowsPowerShell |
46+
dsc resource list -a Microsoft.Adapter/WindowsPowerShell |
4747
ConvertFrom-Json |
4848
Out-GridView
4949
```
@@ -83,7 +83,7 @@ Each of the following commands improves the output in a different way:
8383
experience for screen readers.
8484

8585
```powershell
86-
dsc resource list -a Microsoft.Windows/WindowsPowerShell |
86+
dsc resource list -a Microsoft.Adapter/WindowsPowerShell |
8787
ConvertFrom-Json |
8888
Where-Object {$_.type -like "*process*" } |
8989
Select-Object -Property Type, Kind, Version |

‎docs/concepts/resources/overview.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ DSC supports several kinds of resources:
2929
resource instances and processes them. Group resources can apply special handling to their nested
3030
resource instances, like changing the user the resources run as.
3131
- An _adapter resource_ is a group resource that enables the use of noncommand resources with DSC.
32-
For example, the `Microsoft.DSC/PowerShell` and `Microsoft.Windows/WindowsPowerShell` adapter
32+
For example, the `Microsoft.Adapter/PowerShell` and `Microsoft.Adapter/WindowsPowerShell` adapter
3333
resources enable the use of PowerShell DSC (PSDSC) resources in DSC, invoking the resources in
3434
PowerShell and Windows PowerShell respectively.
3535

‎docs/get-started/index.md‎

Lines changed: 0 additions & 542 deletions
This file was deleted.

‎docs/overview.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,13 +53,13 @@ DSC differs from PowerShell Desired State Configuration (PSDSC) in a few importa
5353

5454
- DSC doesn't _depend_ on PowerShell, Windows PowerShell, or the [PSDesiredStateConfiguration][01]
5555
PowerShell module. DSC provides full compatibility with PSDSC resources through the
56-
`Microsoft.DSC/PowerShell` and `Microsoft.Windows/WindowsPowerShell` _adapter resources_.
56+
`Microsoft.Adapter/PowerShell` and `Microsoft.Adapter/WindowsPowerShell` _adapter resources_.
5757

58-
With the `Microsoft.DSC/PowerShell` adapter resource, you can use any PSDSC resource implemented
58+
With the `Microsoft.Adapter/PowerShell` adapter resource, you can use any PSDSC resource implemented
5959
as a PowerShell class. The resource handles discovering, validating, and invoking PSDSC
6060
resources in PowerShell. The resource is included in the DSC install package for every platform.
6161

62-
With the `Microsoft.Windows/WindowsPowerShell` adapter resource, you can use any PSDSC resource
62+
With the `Microsoft.Adapter/WindowsPowerShell` adapter resource, you can use any PSDSC resource
6363
compatible with Windows PowerShell. The resource handles discovering, validating, and invoking
6464
PSDSC resources in Windows PowerShell. The resource is included in the DSC install packages for
6565
Windows only.

‎docs/reference/cli/resource/list.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -145,14 +145,14 @@ adds the returned list of adapted resources to the discovered resource list. DSC
145145
further filters specified with the command after this enumeration.
146146

147147
```sh
148-
dsc resource list --adapter Microsoft.Windows/WindowsPowerShell
148+
dsc resource list --adapter Microsoft.Adapter/WindowsPowerShell
149149
```
150150

151151
This next command specifies the resource name filter `*Windows*`, limiting the list of returned
152152
resources:
153153

154154
```sh
155-
dsc resource list --adapter Microsoft.Windows/WindowsPowerShell *Windows*
155+
dsc resource list --adapter Microsoft.Adapter/WindowsPowerShell *Windows*
156156
```
157157

158158
## Arguments

‎docs/reference/resources/Microsoft/adapter/powershell/examples/configure-a-machine.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
description: >
3+
Example showing how to configure a machine using multiple class-based PowerShell DSC resources
4+
with the Microsoft.Adapter/PowerShell adapter in a DSC configuration document.
5+
6+
ms.date: 03/23/2026
7+
ms.topic: reference
8+
title: Configure a machine with the PowerShell adapter
9+
---
10+
11+
This example shows how to use the `Microsoft.Adapter/PowerShell` adapter to configure a machine
12+
using multiple class-based PowerShell DSC resources in a single configuration document. These
13+
examples use the `Microsoft.WinGet.DSC/WinGetPackage` resource from the **Microsoft.WinGet.DSC**
14+
module to ensure several packages are installed.
15+
16+
> [!NOTE]
17+
> Run this example with `dsc.exe` version 3.2.0 or later and the **Microsoft.WinGet.DSC**
18+
> PowerShell module installed. Install the module with:
19+
> `Install-PSResource Microsoft.WinGet.DSC`
20+
21+
## Configuration document
22+
23+
The following configuration document defines multiple `Microsoft.WinGet.DSC/WinGetPackage`
24+
instances. Each instance sets `directives.requireAdapter` to `Microsoft.Adapter/PowerShell`.
25+
26+
Save the following YAML as `dev-tools.dsc.yaml`:
27+
28+
```yaml
29+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
30+
parameters:
31+
ensureTools:
32+
type: string
33+
defaultValue: Present
34+
allowedValues:
35+
- Present
36+
- Absent
37+
resources:
38+
- name: PowerShell 7
39+
type: Microsoft.WinGet.DSC/WinGetPackage
40+
directives:
41+
requireAdapter: Microsoft.Adapter/PowerShell
42+
properties:
43+
Id: Microsoft.PowerShell
44+
Ensure: "[parameters('ensureTools')]"
45+
- name: Windows Terminal
46+
type: Microsoft.WinGet.DSC/WinGetPackage
47+
directives:
48+
requireAdapter: Microsoft.Adapter/PowerShell
49+
properties:
50+
Id: Microsoft.WindowsTerminal
51+
Ensure: "[parameters('ensureTools')]"
52+
- name: Visual Studio Code
53+
type: Microsoft.WinGet.DSC/WinGetPackage
54+
directives:
55+
requireAdapter: Microsoft.Adapter/PowerShell
56+
properties:
57+
Id: Microsoft.VisualStudioCode
58+
Ensure: "[parameters('ensureTools')]"
59+
```
60+
61+
## Test the configuration
62+
63+
Run the configuration test to check whether the packages are installed:
64+
65+
```powershell
66+
dsc config test --file dev-tools.dsc.yaml
67+
```
68+
69+
DSC reports the results for each instance, showing which packages need to be installed.
70+
71+
## Apply the configuration
72+
73+
Run the configuration set to install any packages that aren't already present:
74+
75+
```powershell
76+
dsc config set --file dev-tools.dsc.yaml
77+
```
78+
79+
## Remove the packages
80+
81+
To uninstall the packages, override the `ensureTools` parameter when applying the configuration:
82+
83+
```powershell
84+
dsc config set --file dev-tools.dsc.yaml --parameters '{"ensureTools": "Absent"}'
85+
```
86+
87+
<!-- Link references -->
88+
[01]: ../../../../../../cli/config/test.md
89+
[02]: ../../../../../../cli/config/set.md

‎docs/reference/resources/Microsoft/adapter/powershell/examples/invoke-a-resource.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
description: >
3+
Example showing how to invoke a class-based PowerShell DSC resource using
4+
Microsoft.Adapter/PowerShell in a DSC configuration document.
5+
ms.date: 03/23/2026
6+
ms.topic: reference
7+
title: Invoke a resource with the PowerShell adapter
8+
---
9+
10+
This example shows how to use the `Microsoft.Adapter/PowerShell` adapter to invoke a class-based
11+
PowerShell DSC resource. These examples use the `Microsoft.WinGet.DSC/WinGetPackage` resource from
12+
the **Microsoft.WinGet.DSC** module to check whether Windows Terminal is installed.
13+
14+
> [!NOTE]
15+
> Run this example with `dsc.exe` version 3.2.0 or later and the **Microsoft.WinGet.DSC**
16+
> PowerShell module installed. Install the module with:
17+
> `Install-PSResource Microsoft.WinGet.DSC`
18+
19+
## Test whether a WinGet package is installed
20+
21+
The following configuration document defines a single `Microsoft.WinGet.DSC/WinGetPackage`
22+
instance that uses `directives.requireAdapter` to route the resource through the
23+
`Microsoft.Adapter/PowerShell` adapter.
24+
25+
Save the following YAML as `winget-test.dsc.yaml`:
26+
27+
```yaml
28+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
29+
resources:
30+
- name: Windows Terminal
31+
type: Microsoft.WinGet.DSC/WinGetPackage
32+
directives:
33+
requireAdapter: Microsoft.Adapter/PowerShell
34+
properties:
35+
Id: Microsoft.WindowsTerminal
36+
Ensure: Present
37+
```
38+
39+
Run the configuration test operation to check whether Windows Terminal is installed:
40+
41+
```powershell
42+
dsc config test --file winget-test.dsc.yaml
43+
```
44+
45+
When the package isn't installed, DSC returns the following result:
46+
47+
```yaml
48+
metadata:
49+
Microsoft.DSC:
50+
version: 3.2.0
51+
operation: test
52+
executionType: actual
53+
startDatetime: '2026-03-23T00:00:00.000000000+00:00'
54+
endDatetime: '2026-03-23T00:00:01.000000000+00:00'
55+
duration: PT1S
56+
securityContext: restricted
57+
results:
58+
- metadata:
59+
Microsoft.DSC:
60+
duration: PT0.5S
61+
name: Windows Terminal
62+
type: Microsoft.WinGet.DSC/WinGetPackage
63+
result:
64+
desiredState:
65+
Id: Microsoft.WindowsTerminal
66+
Ensure: Present
67+
actualState:
68+
Id: Microsoft.WindowsTerminal
69+
Ensure: Absent
70+
inDesiredState: false
71+
differingProperties:
72+
- Ensure
73+
messages: []
74+
hadErrors: false
75+
```
76+
77+
The `inDesiredState` field is `false` and `differingProperties` shows that `Ensure` differs between
78+
the desired state and the actual state.
79+
80+
## Install a WinGet package
81+
82+
Use the `dsc config set` command to configure the system to the desired state:
83+
84+
```powershell
85+
dsc config set --file winget-test.dsc.yaml
86+
```
87+
88+
When the resource installs the package, DSC returns the following result:
89+
90+
```yaml
91+
metadata:
92+
Microsoft.DSC:
93+
version: 3.2.0
94+
operation: set
95+
executionType: actual
96+
startDatetime: '2026-03-23T00:00:00.000000000+00:00'
97+
endDatetime: '2026-03-23T00:00:05.000000000+00:00'
98+
duration: PT5S
99+
securityContext: restricted
100+
results:
101+
- metadata:
102+
Microsoft.DSC:
103+
duration: PT4S
104+
name: Windows Terminal
105+
type: Microsoft.WinGet.DSC/WinGetPackage
106+
result:
107+
beforeState:
108+
Id: Microsoft.WindowsTerminal
109+
Ensure: Absent
110+
afterState:
111+
Id: Microsoft.WindowsTerminal
112+
Ensure: Present
113+
changedProperties:
114+
- Ensure
115+
messages: []
116+
hadErrors: false
117+
```

0 commit comments

Comments
 (0)