Skip to content

Commit 0d6972e

Browse files
michaeltlombardimichaeltlombardi
authored
Merge pull request #857 from Gijsreyn/update-reference-docs
Add RebootPending and WindowsPowerShell reference documentation
2 parents 2c5b5c7 + 8130f87 commit 0d6972e

File tree

7 files changed

+987
-3
lines changed

7 files changed

+987
-3
lines changed

‎docs/reference/resources/Microsoft/DSC/PowerShell/index.md

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,12 @@ resources:
3232
- name: <nested instance name>
3333
type: <module name>/<class name>
3434
properties: # adapted resource properties
35+
36+
# Or from v3.1.0-preview.2 onwards
37+
resources:
38+
- name: <instanceName>
39+
type: <moduleName>/<class name>
40+
properties: # adapted resource properties
3541
```
3642
3743
## Description
@@ -42,7 +48,7 @@ implemented as PowerShell classes.
4248

4349
The adapter manages the PSDSC resources in PowerShell, not Windows PowerShell. To use MOF-based
4450
PSDSC resources or PSDSC resources that require Windows PowerShell, use the
45-
[Microsoft.Windows/WindowsPowerShell](../../windows/windowspowershell/resource.md) adapter.
51+
[Microsoft.Windows/WindowsPowerShell](../../windows/windowspowershell/index.md) adapter.
4652

4753
This adapter doesn't use the **PSDesiredStateConfiguration** module. You don't need to install the
4854
**PSDesiredStateConfiguration** module to use PSDSC resources in DSC through this adapter.
@@ -62,7 +68,7 @@ for each platform.
6268
| macOS | `$HOME/.dsc/PSAdapterCache.json` |
6369
| Windows | `%LOCALAPPDATA%\dsc\PSAdapterCache.json` |
6470

65-
The adapter versions the cache. The current version is `1`. If the version of the cache on a
71+
The adapter versions the cache. The current version is `2`. If the version of the cache on a
6672
machine differs from the current version, the adapter refreshes the cache.
6773

6874
The adapter checks whether the cache is stale on each run and refreshes it if:
@@ -82,7 +88,7 @@ $adapterScript = dsc resource list Microsoft.DSC/PowerShell |
8288
Select-Object -ExpandProperty directory |
8389
Join-Path
8490
85-
& $adapterScript -Operation CLearCache
91+
& $adapterScript -Operation ClearCache
8692
```
8793

8894
## Requirements

‎docs/reference/resources/Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
description: >
3+
Example showing how to use the Microsoft.Windows/RebootPending resource with DSC to check if a Windows system has a pending reboot.
4+
ms.date: 03/25/2025
5+
ms.topic: reference
6+
title: Check for pending reboot
7+
---
8+
9+
# Check for pending reboot
10+
11+
This example shows how you can use the `Microsoft.Windows/RebootPending` resource to check whether a Windows system has a pending reboot.
12+
13+
## Check reboot status
14+
15+
The following snippet shows how to use the resource with the [dsc resource get][01] command to retrieve the pending reboot status.
16+
17+
```powershell
18+
dsc resource get --resource Microsoft.Windows/RebootPending
19+
```
20+
21+
When you run this command, DSC returns the following result if a reboot is pending:
22+
23+
```yaml
24+
actualState:
25+
rebootPending: true
26+
```
27+
28+
If no reboot is pending, the result is:
29+
30+
```yaml
31+
actualState:
32+
rebootPending: false
33+
```
34+
35+
The `rebootPending` property indicates whether the system requires a reboot (`true`) or not (`false`).
36+
37+
> The resource doesn't implement the **Set**, **WhatIf**, **Export**, **Delete**, or **Test**
38+
> capabilities. You can't use this resource to enforce or export configurations.
39+
>
40+
> Note that even though the resource doesn't implement **Test**, you can still invoke the test
41+
> operation against the resource and use it in the `Microsoft.Dsc/Assertion` group resource. This
42+
> resource relies on the synthetic testing provided by DSC. For more information about synthetic
43+
> testing with DSC, see
44+
> [DSC resource capabiltiies](../../../../../concepts/resources/capabilities.md#test).
45+
>
46+
> For an example using this resource in an assertion, see
47+
> [Use the RebootPending resource in a configuration](./use-rebootpending-in-configuration.md).
48+
49+
<!-- Link reference definitions -->
50+
[01]: ../../../../../cli/resource/get.md

‎docs/reference/resources/Microsoft/Windows/RebootPending/examples/pendingReboot.config.dsc.yaml

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
2+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
3+
resources:
4+
- name: Managed key
5+
type: Microsoft.Windows/Registry
6+
properties:
7+
_exist: true
8+
keyPath: HKCU\DscExamples\ManagedKey
9+
dependsOn:
10+
- "[resourceId('Microsoft.DSC/Assertion','Assert pending reboot')]"
11+
- name: Assert pending reboot
12+
type: Microsoft.DSC/Assertion
13+
properties:
14+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
15+
resources:
16+
- name: Check pending reboot
17+
type: Microsoft.Windows/RebootPending
18+
properties:
19+
rebootPending: true

‎docs/reference/resources/Microsoft/Windows/RebootPending/examples/use-rebootpending-in-configuration.md

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
---
2+
description: >
3+
Example showing how to use the Microsoft.Windows/RebootPending resource in a
4+
configuration document with an assertion to check for a pending reboot.
5+
ms.date: 03/25/2025
6+
ms.topic: reference
7+
title: Use RebootPending resource in a configuration
8+
---
9+
10+
# Use the RebootPending resource in a configuration
11+
12+
This example demonstrates how to use the `Microsoft.Windows/RebootPending` resource in a configuration document.
13+
The configuration checks if a reboot is pending and, if so, skips the subsequent step using an assertion.
14+
15+
## Definition
16+
17+
This configuration document demonstrates how to use the `Microsoft.Windows/RebootPending` resource together with an assertion.
18+
19+
The first instance defines the desired state for the `ManagedKey` registry key, ensuring it
20+
exists only if no reboot is pending. It uses the `dependsOn` property to reference the assertion resource,
21+
which checks the system's reboot status using the `Microsoft.Windows/RebootPending` resource.
22+
The assertion passes when `rebootPending` is `false`,allowing the registry key resource to run.
23+
If a reboot is pending, the assertion fails and the registry key is not set.
24+
25+
:::code language="yaml" source="pendingReboot.config.dsc.yaml":::
26+
27+
Copy the configuration document and save it as `pendingReboot.config.dsc.yaml`.
28+
29+
## Test configuration
30+
31+
To see whether the system is in the desired state, use the [dsc config test][01] command on the
32+
configuration document.
33+
34+
```powershell
35+
dsc config test --file ./pendingReboot.config.dsc.yaml
36+
```
37+
38+
```yaml
39+
metadata:
40+
Microsoft.DSC:
41+
version: 3.0.0
42+
operation: test
43+
executionType: actual
44+
startDatetime: 2025-06-03T06:49:22.573486200+02:00
45+
endDatetime: 2025-06-03T06:49:35.813770500+02:00
46+
duration: PT13.2402843S
47+
securityContext: restricted
48+
results:
49+
- metadata:
50+
Microsoft.DSC:
51+
duration: PT10.0162818S
52+
name: Assert pending reboot
53+
type: Microsoft.DSC/Assertion
54+
result:
55+
desiredState:
56+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
57+
resources:
58+
- name: Check pending reboot
59+
type: Microsoft.Windows/RebootPending
60+
properties:
61+
rebootPending: false
62+
actualState:
63+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
64+
contentVersion: 1.0.0
65+
resources:
66+
- type: Microsoft.Windows/RebootPending
67+
name: Check pending reboot
68+
properties:
69+
rebootPending: false
70+
inDesiredState: true
71+
differingProperties: []
72+
- metadata:
73+
Microsoft.DSC:
74+
duration: PT0.0549784S
75+
name: Managed key
76+
type: Microsoft.Windows/Registry
77+
result:
78+
desiredState:
79+
_exist: true
80+
keyPath: HKCU\DscExamples\ManagedKey
81+
actualState:
82+
keyPath: HKCU\DscExamples\ManagedKey
83+
_exist: false
84+
inDesiredState: false
85+
differingProperties:
86+
- _exist
87+
messages: []
88+
hadErrors: false
89+
```
90+
91+
Review the individual results to understand whether each instance is in the desired state.
92+
93+
The result for the first instance, named `Check pending reboot`, was:
94+
95+
```yaml
96+
desiredState:
97+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
98+
resources:
99+
- name: Check pending reboot
100+
type: Microsoft.Windows/RebootPending
101+
properties:
102+
rebootPending: false
103+
actualState:
104+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
105+
contentVersion: 1.0.0
106+
resources:
107+
- type: Microsoft.Windows/RebootPending
108+
name: Check pending reboot
109+
properties:
110+
rebootPending: false
111+
inDesiredState: true
112+
differingProperties: []
113+
```
114+
115+
The output indicates there is no pending reboot. When you use the **Set** operation on
116+
this confifguration, the second instance will run.
117+
118+
The result for the second instance, named `Managed value`, was:
119+
120+
```yaml
121+
desiredState:
122+
_exist: true
123+
keyPath: HKCU\DscExamples\ManagedKey
124+
actualState:
125+
keyPath: HKCU\DscExamples\ManagedKey
126+
_exist: false
127+
inDesiredState: false
128+
differingProperties:
129+
- _exist
130+
```
131+
132+
The output indicates the registry path doesn't exist.
133+
134+
The first instance indicates the resource is in the desired state. The second
135+
instance indicates it isn't in the desired state.
136+
137+
## Enforce configuration
138+
139+
To update the system to the desired state, use the [dsc config set][02] command on the configuration document.
140+
141+
```powershell
142+
dsc config set --file ./pendingReboot.config.dsc.yaml
143+
```
144+
145+
```yaml
146+
metadata:
147+
Microsoft.DSC:
148+
version: 3.0.0
149+
operation: set
150+
executionType: actual
151+
startDatetime: 2025-06-03T06:55:12.123456+02:00
152+
endDatetime: 2025-06-03T06:55:15.654321+02:00
153+
duration: PT3.530865S
154+
securityContext: restricted
155+
results:
156+
- metadata:
157+
Microsoft.DSC:
158+
duration: PT2.000000S
159+
name: Assert pending reboot
160+
type: Microsoft.DSC/Assertion
161+
result:
162+
beforeState:
163+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
164+
resources:
165+
- name: Check pending reboot
166+
type: Microsoft.Windows/RebootPending
167+
properties:
168+
rebootPending: false
169+
afterState:
170+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
171+
resources:
172+
- name: Check pending reboot
173+
type: Microsoft.Windows/RebootPending
174+
properties:
175+
rebootPending: false
176+
changedProperties: []
177+
- metadata:
178+
Microsoft.DSC:
179+
duration: PT0.0549784S
180+
name: Managed key
181+
type: Microsoft.Windows/Registry
182+
result:
183+
beforeState:
184+
keyPath: HKCU\DscExamples\ManagedKey
185+
_exist: false
186+
afterState:
187+
keyPath: HKCU\DscExamples\ManagedKey
188+
changedProperties:
189+
- _exist
190+
messages: []
191+
hadErrors: false
192+
```
193+
194+
Review the individual results to understand how the resource modified the system to enforce the desired state for each instance.
195+
196+
The result for the assertion instance, named `Assert pending reboot`, was:
197+
198+
```yaml
199+
beforeState:
200+
- name: Check pending reboot
201+
type: Microsoft.Windows/RebootPending
202+
result:
203+
actualState:
204+
rebootPending: false
205+
afterState:
206+
- metadata:
207+
Microsoft.DSC:
208+
duration: PT0.5209322S
209+
name: Check pending reboot
210+
type: Microsoft.Windows/RebootPending
211+
result:
212+
desiredState:
213+
rebootPending: false
214+
actualState:
215+
rebootPending: false
216+
inDesiredState: true
217+
differingProperties: []
218+
changedProperties: []
219+
```
220+
221+
The output indicates the assertion passed and no changes were needed.
222+
223+
The result for the registry key instance, named `Managed key`, was:
224+
225+
```yaml
226+
beforeState:
227+
keyPath: HKCU\DscExamples\ManagedKey
228+
_exist: false
229+
afterState:
230+
keyPath: HKCU\DscExamples\ManagedKey
231+
changedProperties:
232+
- _exist
233+
```
234+
235+
The output indicates that the resource created the registry key.
236+
237+
## Cleanup
238+
239+
To return your system to its original state:
240+
241+
1. Save the following configuration as `registry.cleanup.config.dsc.yaml`.
242+
243+
:::code language="yaml" source="../../Registry/examples/registry.cleanup.config.dsc.yaml":::
244+
245+
2. Use the **Set** operation on the cleanup configuration document.
246+
247+
```powershell
248+
dsc config set --file ./registry.cleanup.config.dsc.yaml
249+
```
250+
251+
<!-- Link reference definitions -->
252+
[01]: ../../../../../cli/config/test.md
253+
[02]: ../../../../../cli/config/set.md

0 commit comments

Comments
 (0)