Skip to content

Commit 0ee5659

Browse files
SteveL-MSFTSteveL-MSFT
authored
Merge pull request #1522 from Gijsreyn/update-winservice-docs
docs: Add reference documentation for `Microsoft.Windows/Service`
2 parents aa3e331 + c900882 commit 0ee5659

4 files changed

Lines changed: 723 additions & 0 deletions

File tree

‎docs/reference/resources/Microsoft/Windows/Service/examples/configure-windows-service.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
description: >
3+
Example showing how to use the Microsoft.Windows/Service resource in a DSC configuration
4+
document to enforce the desired state of Windows services.
5+
ms.date: 05/08/2026
6+
ms.topic: reference
7+
title: Configure a Windows service
8+
---
9+
10+
# Configure a Windows service
11+
12+
This example shows how you can use the `Microsoft.Windows/Service` resource in a DSC configuration
13+
document to enforce the desired configuration and runtime status of multiple Windows services.
14+
15+
> [!IMPORTANT]
16+
> **Set** operations for this resource require an elevated (administrator) process context. Run
17+
> your terminal or PowerShell session as Administrator before using `dsc config set`.
18+
19+
## Definition
20+
21+
The configuration document for this example defines two instances of the `Service` resource.
22+
23+
The first instance ensures that the Print Spooler service (`Spooler`) is stopped and configured
24+
for manual start. The second instance ensures that the Windows Time service (`W32Time`) is running
25+
and configured to start automatically.
26+
27+
:::code language="yaml" source="service.config.dsc.yaml":::
28+
29+
Copy the configuration document and save it as `service.config.dsc.yaml`.
30+
31+
## Setup
32+
33+
The output in this example assumes that the system has the `Spooler` service stopped with a manual
34+
startup and the `W32Time` service stopped with an automatic startup. You can set the system to
35+
this starting state with the following commands:
36+
37+
```powershell
38+
Set-Service -Name Spooler -StartupType Manual -Status Stopped
39+
Set-Service -Name W32Time -StartupType Automatic -Status Stopped
40+
```
41+
42+
## Test the configuration
43+
44+
To see whether the system is already in the desired state, use the [dsc config test][01] command.
45+
46+
```powershell
47+
dsc config test --file ./service.config.dsc.yaml
48+
```
49+
50+
```yaml
51+
executionInformation:
52+
# Elided for brevity
53+
metadata:
54+
# Elided for brevity
55+
results:
56+
- executionInformation:
57+
duration: PT0.1113118S
58+
metadata:
59+
Microsoft.DSC:
60+
duration: PT0.1113118S
61+
name: Ensure Print Spooler is stopped and set to manual start
62+
type: Microsoft.Windows/Service
63+
result:
64+
desiredState:
65+
name: Spooler
66+
status: Stopped
67+
startType: Manual
68+
actualState:
69+
name: Spooler
70+
displayName: Print Spooler
71+
description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers.
72+
_exist: true
73+
status: Stopped
74+
startType: Manual
75+
executablePath: C:\Windows\System32\spoolsv.exe
76+
logonAccount: LocalSystem
77+
errorControl: Normal
78+
dependencies:
79+
- RPCSS
80+
inDesiredState: true
81+
differingProperties: []
82+
- executionInformation:
83+
duration: PT0.0353328S
84+
metadata:
85+
Microsoft.DSC:
86+
duration: PT0.0353328S
87+
name: Ensure Windows Time service is running
88+
type: Microsoft.Windows/Service
89+
result:
90+
desiredState:
91+
name: W32Time
92+
status: Running
93+
startType: Automatic
94+
actualState:
95+
name: W32Time
96+
displayName: Windows Time
97+
description: Maintains date and time synchronization on all clients and servers in the network. If this service is stopped, date and time synchronization will be unavailable. If this service is disabled, any services that explicitly depend on it will fail to start.
98+
_exist: true
99+
status: Stopped
100+
startType: Automatic
101+
executablePath: C:\Windows\system32\svchost.exe -k LocalService
102+
logonAccount: NT AUTHORITY\LocalService
103+
errorControl: Normal
104+
inDesiredState: false
105+
differingProperties:
106+
- status
107+
messages: []
108+
hadErrors: false
109+
```
110+
111+
The `inDesiredState` field for the first instance is `true` because the Print Spooler service is
112+
already `Stopped` with `Manual` start, so no change is required. The second instance is `false`:
113+
the Windows Time service exists and already has `startType: Automatic`, but its `status` is
114+
`Stopped` while the desired state requires `Running`. Only `status` is listed in
115+
`differingProperties`.
116+
117+
## Set the configuration
118+
119+
To enforce the desired state, use the [dsc config set][02] command.
120+
121+
```powershell
122+
dsc config set --file ./service.config.dsc.yaml
123+
```
124+
125+
```yaml
126+
executionInformation:
127+
# Elided for brevity
128+
metadata:
129+
# Elided for brevity
130+
results:
131+
- executionInformation:
132+
duration: PT0.0924309S
133+
metadata:
134+
Microsoft.DSC:
135+
duration: PT0.0924309S
136+
name: Ensure Print Spooler is stopped and set to manual start
137+
type: Microsoft.Windows/Service
138+
result:
139+
beforeState:
140+
name: Spooler
141+
status: Stopped
142+
startType: Manual
143+
afterState:
144+
name: Spooler
145+
displayName: Print Spooler
146+
description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers.
147+
_exist: true
148+
status: Stopped
149+
startType: Manual
150+
executablePath: C:\Windows\System32\spoolsv.exe
151+
logonAccount: LocalSystem
152+
errorControl: Normal
153+
dependencies:
154+
- RPCSS
155+
changedProperties: null
156+
- executionInformation:
157+
duration: PT0.3682548S
158+
metadata:
159+
Microsoft.DSC:
160+
duration: PT0.3682548S
161+
name: Ensure Windows Time service is running
162+
type: Microsoft.Windows/Service
163+
result:
164+
beforeState:
165+
name: W32Time
166+
displayName: Windows Time
167+
description: Maintains date and time synchronization on all clients and servers in the network. If this service is stopped, date and time synchronization will be unavailable. If this service is disabled, any services that explicitly depend on it will fail to start.
168+
_exist: true
169+
status: Stopped
170+
startType: Automatic
171+
executablePath: C:\Windows\system32\svchost.exe -k LocalService
172+
logonAccount: NT AUTHORITY\LocalService
173+
errorControl: Normal
174+
afterState:
175+
name: W32Time
176+
displayName: Windows Time
177+
description: Maintains date and time synchronization on all clients and servers in the network. If this service is stopped, date and time synchronization will be unavailable. If this service is disabled, any services that explicitly depend on it will fail to start.
178+
_exist: true
179+
status: Running
180+
startType: Automatic
181+
executablePath: C:\Windows\system32\svchost.exe -k LocalService
182+
logonAccount: NT AUTHORITY\LocalService
183+
errorControl: Normal
184+
changedProperties:
185+
- status
186+
messages: []
187+
hadErrors: false
188+
```
189+
190+
The Print Spooler instance shows `changedProperties: null` because it was already in the desired
191+
state and DSC made no changes to it. The Windows Time instance lists only `status` in
192+
`changedProperties` because DSC only needed to start the service. The `startType` was already
193+
`Automatic` and required no update.
194+
195+
<!-- Link definitions -->
196+
[01]: ../../../../../cli/config/test.md
197+
[02]: ../../../../../cli/config/set.md

‎docs/reference/resources/Microsoft/Windows/Service/examples/get-service-status.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
description: >
3+
Example showing how to use the Microsoft.Windows/Service resource with DSC to retrieve the
4+
current state of a Windows service.
5+
ms.date: 05/08/2026
6+
ms.topic: reference
7+
title: Get service status
8+
---
9+
10+
# Get service status
11+
12+
This example shows how you can use the `Microsoft.Windows/Service` resource to retrieve the
13+
current configuration and runtime status of a Windows service.
14+
15+
## Get the state of a service by name
16+
17+
The following snippet shows how to use the resource with the [dsc resource get][01] command to
18+
retrieve the current state of the `wuauserv` (Windows Update) service by its key name.
19+
20+
```powershell
21+
$instance = @{ name = 'wuauserv' } | ConvertTo-Json -Compress
22+
23+
dsc resource get --resource Microsoft.Windows/Service --input $instance
24+
```
25+
26+
When the service exists, DSC returns its full configuration and status:
27+
28+
```yaml
29+
actualState:
30+
name: wuauserv
31+
displayName: Windows Update
32+
description: Enables the detection, download, and installation of updates for Windows and other programs. If this service is disabled, users of this computer will not be able to use Windows Update or its automatic updating feature, and programs will not be able to use the Windows Update Agent (WUA) API.
33+
_exist: true
34+
status: Stopped
35+
startType: Manual
36+
executablePath: C:\WINDOWS\System32\svchost.exe -k netsvcs -p
37+
logonAccount: LocalSystem
38+
errorControl: Normal
39+
dependencies:
40+
- rpcss
41+
```
42+
43+
## Get the state of a service by display name
44+
45+
You can also identify the service by its display name when you don't know the key name.
46+
47+
```powershell
48+
$instance = @{ displayName = 'Windows Update' } | ConvertTo-Json -Compress
49+
50+
dsc resource get --resource Microsoft.Windows/Service --input $instance
51+
```
52+
53+
DSC resolves the display name to the corresponding key name and returns the same result.
54+
55+
## Get the state of a non-existent service
56+
57+
When you request a service that isn't registered with the SCM, the resource returns `_exist: false`
58+
and leaves all other properties unset.
59+
60+
```powershell
61+
$instance = @{ name = 'MyMissingService' } | ConvertTo-Json
62+
63+
dsc resource get --resource Microsoft.Windows/Service --input $instance
64+
```
65+
66+
```yaml
67+
actualState:
68+
name: MyMissingService
69+
_exist: false
70+
```
71+
72+
## Export all services
73+
74+
To retrieve the state of every service registered on the system, use the [dsc resource export][02]
75+
command without an input instance.
76+
77+
```powershell
78+
dsc resource export --resource Microsoft.Windows/Service
79+
```
80+
81+
DSC writes a single JSON configuration document to stdout. That document contains a `resources`
82+
array with one entry per service, which you can pipe to a file or process further with other
83+
tools.
84+
85+
<!-- Link definitions -->
86+
[01]: ../../../../../cli/resource/get.md
87+
[02]: ../../../../../cli/resource/export.md

‎docs/reference/resources/Microsoft/Windows/Service/examples/service.config.dsc.yaml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
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: Ensure Print Spooler is stopped and set to manual start
5+
type: Microsoft.Windows/Service
6+
properties:
7+
name: Spooler
8+
status: Stopped
9+
startType: Manual
10+
- name: Ensure Windows Time service is running
11+
type: Microsoft.Windows/Service
12+
properties:
13+
name: W32Time
14+
status: Running
15+
startType: Automatic

0 commit comments

Comments
 (0)