Skip to content

Commit da95e53

Browse files
Gijsreynmichaeltlombardi
Gijsreyn
authored and
michaeltlombardi
committed
docs: Update PSScript examples
1 parent f84e6e5 commit da95e53

10 files changed

Lines changed: 2789 additions & 48 deletions

File tree

‎docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/examples/configure-with-script.md‎

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
---
2+
description: >
3+
Example showing how use the PowerShellScript resource in a DSC configuration
4+
document.
5+
ms.date: 05/10/2026
6+
ms.topic: reference
7+
title: Configure a system with the PowerShellScript resource
8+
---
9+
10+
<!-- markdownlint-disable MD025 -->
11+
12+
# Configure a system with the PowerShellScript resource
13+
14+
This example shows how you can use the [`Microsoft.DSC.Transitional/PowerShellScript`][01] resource
15+
in a configuration both to invoke non-idempotent scripts and to idempotently manage a message of
16+
the day file that doesn't have a specific DSC resource.
17+
18+
## Definition
19+
20+
The configuration document for this example defines two instances of the resource:
21+
22+
1. The first instance, `Report processor info`, returns the number of processor cores and the
23+
processor architecture from both `getScript` and `setScript`. This instance is informational
24+
only - it doesn't modify the system.
25+
1. The second instance, `Message of the Day`, idempotently manages a message of the day file. It
26+
uses `input` to define the contents of the file and pulls the value for the input from the
27+
`parameters` definition. It defines all three script properties: `getScript` to return the
28+
actual state, `testScript` to determine if the instance is in the desired state, and `setScript`
29+
to enforce the desired state.
30+
31+
The `getScript` and `setScript` definitions return the same structured output representing the
32+
state of the MOTD file to make monitoring how the instance modifies the system easier. All three
33+
script definitions use the `Write-Verbose` cmdlet to emit informational messages about what the
34+
instance is doing. In particular the messages from `testScript` describe whether and how the
35+
file isn't in the desired state to address the limited information the script can surface in its
36+
output.
37+
38+
:::code language="yaml" source="registry.config.dsc.yaml":::
39+
40+
Copy the configuration document and save it as `psscript.config.dsc.yaml`.
41+
42+
## Get the current state
43+
44+
To retrieve the current state of the system, use the [dsc config get][02] command on the
45+
configuration document.
46+
47+
```powershell
48+
dsc --trace-level info config get --file ./psscript.config.dsc.yaml
49+
```
50+
51+
```Messages
52+
<timestamp> INFO Trace-level is Info
53+
<timestamp> INFO Discovering 'Extension' using filter: *
54+
<timestamp> INFO Discovering 'Resource' using filter: *
55+
<timestamp> INFO No results returned for discovery extension 'Microsoft.PowerShell/Discover'
56+
<timestamp> INFO Invoking get 'Microsoft.DSC.Transitional/PowerShellScript' using 'pwsh'
57+
<timestamp> INFO Invoking get 'Microsoft.DSC.Transitional/PowerShellScript' using 'pwsh'
58+
<timestamp> INFO PID <pid>: Checking for MOTD file at 'Temp:/example.motd'
59+
<timestamp> INFO PID <pid>: MOTD file not found at 'Temp:/example.motd
60+
```
61+
62+
```yaml
63+
executionInformation:
64+
# Elided for brevity
65+
metadata:
66+
Microsoft.DSC:
67+
# Elided for brevity
68+
results:
69+
- executionInformation:
70+
duration: PT1.2985379S
71+
metadata:
72+
Microsoft.DSC:
73+
duration: PT1.2985379S
74+
name: Report processor info
75+
type: Microsoft.DSC.Transitional/PowerShellScript
76+
result:
77+
actualState:
78+
output:
79+
- processorCount: 8
80+
processorArchitecture: X64
81+
- executionInformation:
82+
duration: PT0.9556133S
83+
metadata:
84+
Microsoft.DSC:
85+
duration: PT0.9556133S
86+
name: Message of the Day
87+
type: Microsoft.DSC.Transitional/PowerShellScript
88+
result:
89+
actualState:
90+
output:
91+
- filePath: Temp:/example.motd
92+
exists: false
93+
messages: []
94+
hadErrors: false
95+
```
96+
97+
The command emitted messages to stderr and the result to stdout. The messages include informational
98+
messages from `getScript` for the message of the day instance indicating that the script looked for
99+
but did not find the MOTD file.
100+
101+
The result includes structured output from both instances:
102+
103+
- The processor report instance shows that the system has `8` cores and is an `X64` architecture.
104+
- The message of the day instance shows that the expected MOTD file doesn't exist at
105+
`Temp:/example.motd`.
106+
107+
## Enforce the desired state
108+
109+
To update the system to the desired state, use the [dsc config set][03] command on the
110+
configuration document.
111+
112+
```powershell
113+
dsc --trace-level info config set --file ./psscript.config.dsc.yaml
114+
```
115+
116+
```Messages
117+
<timestamp> INFO Trace-level is Info
118+
<timestamp> INFO Discovering 'Extension' using filter: *
119+
<timestamp> INFO Discovering 'Resource' using filter: *
120+
<timestamp> INFO No results returned for discovery extension 'Microsoft.PowerShell/Discover'
121+
<timestamp> INFO Getting current state for set by invoking get on 'Microsoft.DSC.Transitional/PowerShellScript' using 'pwsh'
122+
<timestamp> INFO Getting current state for set by invoking get on 'Microsoft.DSC.Transitional/PowerShellScript' using 'pwsh'
123+
<timestamp> INFO PID <pid>: Checking for MOTD file at 'Temp:/example.motd'
124+
<timestamp> INFO PID <pid>: MOTD file not found at 'Temp:/example.motd'
125+
<timestamp> INFO PID <pid>: MOTD file not found at 'Temp:/example.motd', creating new file
126+
<timestamp> INFO PID <pid>: MOTD file created at 'Temp:/example.motd', setting content
127+
<timestamp> INFO diff: key 'motd' missing
128+
<timestamp> INFO diff: key 'lastUpdated' missing
129+
<timestamp> INFO diff: actual array missing expected item
130+
<timestamp> INFO diff: arrays differ for 'output
131+
```
132+
133+
```yaml
134+
executionInformation:
135+
# Elided for brevity
136+
metadata:
137+
Microsoft.DSC:
138+
# Elided for brevity
139+
results:
140+
- executionInformation:
141+
duration: PT2.1871641S
142+
metadata:
143+
Microsoft.DSC:
144+
duration: PT2.1871641S
145+
name: Report processor info
146+
type: Microsoft.DSC.Transitional/PowerShellScript
147+
result:
148+
beforeState:
149+
output:
150+
- processorCount: 8
151+
processorArchitecture: X64
152+
afterState:
153+
output:
154+
- processorCount: 8
155+
processorArchitecture: X64
156+
changedProperties: []
157+
- executionInformation:
158+
duration: PT1.708226S
159+
metadata:
160+
Microsoft.DSC:
161+
duration: PT1.708226S
162+
name: Message of the Day
163+
type: Microsoft.DSC.Transitional/PowerShellScript
164+
result:
165+
beforeState:
166+
output:
167+
- exists: false
168+
filePath: Temp:/example.motd
169+
afterState:
170+
output:
171+
- exists: true
172+
motd: Hello, friend!
173+
filePath: Temp:/example.motd
174+
lastUpdated: 2026-06-02T18:05:16.8811712-05:00
175+
changedProperties:
176+
- output
177+
messages: []
178+
hadErrors: false
179+
```
180+
181+
As before, the message of the day instance surfaces informational messages. The messages show that
182+
the MOTD file wasn't found and then the `setScript` reports that it is creating the file and
183+
setting the content.
184+
185+
It's easier to review the result data for each instance separately:
186+
187+
- ```yaml
188+
name: Report processor info
189+
type: Microsoft.DSC.Transitional/PowerShellScript
190+
result:
191+
beforeState:
192+
output:
193+
- processorCount: 8
194+
processorArchitecture: X64
195+
afterState:
196+
output:
197+
- processorCount: 8
198+
processorArchitecture: X64
199+
changedProperties: []
200+
```
201+
202+
The processor info report shows the same state for the system before and after the **Set**
203+
operation. If the instance didn't define `setScript` then `afterState` would be an empty object
204+
(`{}`) and the `changedProperties` field would report that `output` was modified. Providing
205+
identical output for the `setScript` ensures that the result doesn't imply any system changes.
206+
207+
- ```yaml
208+
name: Message of the Day
209+
type: Microsoft.DSC.Transitional/PowerShellScript
210+
result:
211+
beforeState:
212+
output:
213+
- exists: false
214+
filePath: Temp:/example.motd
215+
afterState:
216+
output:
217+
- exists: true
218+
motd: Hello, friend!
219+
filePath: Temp:/example.motd
220+
lastUpdated: 2026-06-02T18:05:16.8811712-05:00
221+
changedProperties:
222+
- output
223+
```
224+
225+
The result for the message of the day instance shows that `exists` changed from `false` to `true`.
226+
The `afterState` also includes the `motd` property showing the newly-set MOTD and reports the
227+
last updated time for the file.
228+
229+
If you invoke the **Set** operation for the configuration again you should see that neither instance
230+
modifies the system:
231+
232+
```powershell
233+
dsc --trace-level info config set --file ./psscript.config.dsc.yaml
234+
```
235+
236+
```Messages
237+
<timestamp> INFO Trace-level is Info
238+
<timestamp> INFO Discovering 'Extension' using filter: *
239+
<timestamp> INFO Discovering 'Resource' using filter: *
240+
<timestamp> INFO No results returned for discovery extension 'Microsoft.PowerShell/Discover'
241+
<timestamp> INFO Getting current state for set by invoking get on 'Microsoft.DSC.Transitional/PowerShellScript' using 'pwsh'
242+
<timestamp> INFO Getting current state for set by invoking get on 'Microsoft.DSC.Transitional/PowerShellScript' using 'pwsh'
243+
<timestamp> INFO PID <pid>: Checking for MOTD file at 'Temp:/example.motd'
244+
<timestamp> INFO PID <pid>: MOTD file found at 'Temp:/example.motd', retrieving content and last updated time
245+
<timestamp> INFO PID <pid>: MOTD file found at 'Temp:/example.motd', checking content
246+
<timestamp> INFO PID <pid>: MOTD content matches desired value, no update needed
247+
```
248+
249+
```yaml
250+
executionInformation:
251+
# Elided for brevity
252+
metadata:
253+
Microsoft.DSC:
254+
# Elided for brevity
255+
results:
256+
- executionInformation:
257+
duration: PT3.8028321S
258+
metadata:
259+
Microsoft.DSC:
260+
duration: PT3.8028321S
261+
name: Report processor info
262+
type: Microsoft.DSC.Transitional/PowerShellScript
263+
result:
264+
beforeState:
265+
output:
266+
- processorCount: 8
267+
processorArchitecture: X64
268+
afterState:
269+
output:
270+
- processorCount: 8
271+
processorArchitecture: X64
272+
changedProperties: []
273+
- executionInformation:
274+
duration: PT2.6216447S
275+
metadata:
276+
Microsoft.DSC:
277+
duration: PT2.6216447S
278+
name: Message of the Day
279+
type: Microsoft.DSC.Transitional/PowerShellScript
280+
result:
281+
beforeState:
282+
output:
283+
- filePath: Temp:/example.motd
284+
motd: Hello, friend!
285+
exists: true
286+
lastUpdated: 2026-06-03T08:46:38.0491245-05:00
287+
afterState:
288+
output:
289+
- motd: Hello, friend!
290+
exists: true
291+
lastUpdated: 2026-06-03T08:46:38.0491245-05:00
292+
filePath: Temp:/example.motd
293+
changedProperties: []
294+
messages: []
295+
hadErrors: false
296+
```
297+
298+
## Cleanup
299+
300+
To return your system to its original state, invoke the following PowerShell command to remove the
301+
MOTD file from the `Temp:/` folder:
302+
303+
```powershell
304+
Remove-Item -Path 'Temp:/example.motd' -Verbose
305+
```
306+
307+
<!-- Link reference definitions -->
308+
[01]: ../index.md
309+
[02]: ../../../../../../cli/config/get.md
310+
[03]: ../../../../../../cli/config/set.md

0 commit comments

Comments
 (0)