Skip to content

Commit c229ff7

Browse files
GijsreynGijsreyn
committed
Add documentation
1 parent 390b431 commit c229ff7

File tree

3 files changed

+362
-1
lines changed

3 files changed

+362
-1
lines changed

‎.github/workflows/rust.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ name: Rust
22

33
on:
44
push:
5-
branches: [ "*" ]
5+
branches: [ "main" ]
66
pull_request:
77
branches: [ "main" ]
88
paths-ignore:

‎docs/reference/resources/Microsoft/Windows/WindowsPowerShell/examples/manage-a-windows-service.md

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
---
2+
description: >
3+
Examples showing how you can invoke the Microsoft.Windows/WindowsPowerShell with DSC to manage
4+
a Windows service using the PSDesiredStateConfiguration module.
5+
6+
ms.date: 03/25/2025
7+
ms.topic: reference
8+
title: Manage a Windows service
9+
---
10+
11+
This example shows how you can use the `Microsoft.Windows/WindowsPowerShell` resource with the `PSDesiredStateConfiguration` module to manage a Windows service.
12+
These examples manage the `Spooler` print spooler service.
13+
14+
> [!NOTE]
15+
> Run this example in an elevated PowerShell session with `dsc.exe` version 3.1.0-preview.2 or later.
16+
17+
## Test whether a service is running
18+
19+
The following snippet shows how you can use the resource with the [dsc resource test][01] command to check whether the `Spooler` service is running.
20+
21+
```powershell
22+
$instance = @{
23+
Name = 'Spooler'
24+
StartupType = 'Automatic'
25+
} | ConvertTo-Json
26+
27+
dsc resource test --resource PSDesiredStateConfiguration/Service --input $instance
28+
```
29+
30+
When the service isn't running or has a different startup type, DSC returns the following result:
31+
32+
```yaml
33+
desiredState:
34+
Name: Spooler
35+
StartupType: Manual
36+
actualState:
37+
InDesiredState: false
38+
inDesiredState: false
39+
differingProperties:
40+
- StartupType
41+
```
42+
43+
The `inDesiredState` field of the result object is set to `false`, indicating that the instance isn't in the desired state. The `differingProperties` field indicates that the `property` property is mismatched between the desired state and actual state.
44+
45+
## Ensure a service is running with automatic startup
46+
47+
To set the system to the desired state and configure the service, use the [dsc resource set][02] command.
48+
49+
```powershell
50+
dsc resource set --resource PSDesiredStateConfiguration/Service --input $instance
51+
```
52+
53+
When the resource configures the service, DSC returns the following result:
54+
55+
```yaml
56+
beforeState:
57+
Status: null /
58+
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.
59+
DisplayName: Print Spooler
60+
ResourceId: null
61+
PsDscRunAsCredential: null
62+
Name: Spooler
63+
Credential: null
64+
PSComputerName: localhost
65+
ConfigurationName: null
66+
Ensure: null
67+
DependsOn: null
68+
SourceInfo: null
69+
BuiltInAccount: LocalSystem
70+
StartupType: Manual
71+
State: Running
72+
ModuleVersion: '1.1'
73+
ModuleName: PSDesiredStateConfiguration
74+
Path: C:\WINDOWS\System32\spoolsv.exe
75+
Dependencies:
76+
- RPCSS
77+
- http
78+
afterState:
79+
Status: null
80+
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.
81+
DisplayName: Print Spooler
82+
ResourceId: null
83+
PsDscRunAsCredential: null
84+
Name: Spooler
85+
Credential: null
86+
PSComputerName: localhost
87+
ConfigurationName: null
88+
Ensure: null
89+
DependsOn: null
90+
SourceInfo: null
91+
BuiltInAccount: LocalSystem
92+
StartupType: Automatic
93+
State: Running
94+
ModuleVersion: '1.1'
95+
ModuleName: PSDesiredStateConfiguration
96+
Path: C:\WINDOWS\System32\spoolsv.exe
97+
Dependencies:
98+
- RPCSS
99+
- http
100+
changedProperties:
101+
- StartupType
102+
```
103+
104+
You can test the instance again to confirm that the service is configured correctly:
105+
106+
```powershell
107+
dsc resource test --resource PSDesiredStateConfiguration/Service --input $instance
108+
```
109+
110+
```yaml
111+
desiredState:
112+
Name: Spooler /
113+
StartupType: Manual
114+
actualState:
115+
InDesiredState: true
116+
inDesiredState: true
117+
differingProperties: []
118+
```
119+
120+
## Stop a service
121+
122+
The following snippet shows how you can configure the `Spooler` service to be stopped with manual startup.
123+
124+
```powershell
125+
$stopInstance = @{
126+
Name = 'Spooler'
127+
State = 'Stopped'
128+
StartupType = 'Manual'
129+
} | ConvertTo-Json
130+
131+
dsc resource set --resource PSDesiredStateConfiguration/Service --input $stopInstance
132+
```
133+
134+
When the resource stops the service, DSC returns the following result:
135+
136+
```yaml
137+
beforeState:
138+
Status: null /
139+
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.
140+
DisplayName: Print Spooler
141+
ResourceId: null
142+
PsDscRunAsCredential: null
143+
Name: Spooler
144+
Credential: null
145+
PSComputerName: localhost
146+
ConfigurationName: null
147+
Ensure: null
148+
DependsOn: null
149+
SourceInfo: null
150+
BuiltInAccount: LocalSystem
151+
StartupType: Manual
152+
State: Running
153+
ModuleVersion: '1.1'
154+
ModuleName: PSDesiredStateConfiguration
155+
Path: C:\WINDOWS\System32\spoolsv.exe
156+
Dependencies:
157+
- RPCSS
158+
- http
159+
afterState:
160+
Status: null
161+
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.
162+
DisplayName: Print Spooler
163+
ResourceId: null
164+
PsDscRunAsCredential: null
165+
Name: Spooler
166+
Credential: null
167+
PSComputerName: localhost
168+
ConfigurationName: null
169+
Ensure: null
170+
DependsOn: null
171+
SourceInfo: null
172+
BuiltInAccount: LocalSystem
173+
StartupType: Manual
174+
State: Stopped
175+
ModuleVersion: '1.1'
176+
ModuleName: PSDesiredStateConfiguration
177+
Path: C:\WINDOWS\System32\spoolsv.exe
178+
Dependencies:
179+
- RPCSS
180+
- http
181+
changedProperties:
182+
- State
183+
```
184+
185+
## Verify the current state of a service
186+
187+
To check the current state of the service, use the `dsc resource get` command.
188+
189+
```powershell
190+
dsc resource get --resource PSDesiredStateConfiguration/Service --input $instance
191+
```
192+
193+
```yaml
194+
actualState:
195+
Status: null /
196+
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.
197+
DisplayName: Print Spooler
198+
ResourceId: null
199+
PsDscRunAsCredential: null
200+
Name: Spooler
201+
Credential: null
202+
PSComputerName: localhost
203+
ConfigurationName: null
204+
Ensure: null
205+
DependsOn: null
206+
SourceInfo: null
207+
BuiltInAccount: LocalSystem
208+
StartupType: Manual
209+
State: Stopped
210+
ModuleVersion: '1.1'
211+
ModuleName: PSDesiredStateConfiguration
212+
Path: C:\WINDOWS\System32\spoolsv.exe
213+
Dependencies:
214+
- RPCSS
215+
- http
216+
```
217+
218+
## Restore the original service configuration
219+
220+
If you want to restore the service to its original running state, you can reapply the first configuration.
221+
222+
```powershell
223+
dsc resource set --resource Microsoft.Windows/WindowsPowerShell --input $instance
224+
```
225+
226+
<!-- Link reference definitions -->
227+
[01]: ../../../../../cli/resource/test.md
228+
[02]: ../../../../../cli/resource/set.md

‎docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
description: Microsoft.Windows/WindowsPowerShell resource adapter reference documentation
3+
ms.date: 03/25/2025
4+
ms.topic: reference
5+
title: Microsoft.Windows/WindowsPowerShell
6+
---
7+
8+
# Microsoft.Windows/WindowsPowerShell
9+
10+
## Synopsis
11+
12+
Manage PowerShell DSC resources. This adapter enables you to use class-based, script-based, or binary PowerShell DSC resources available on the system.
13+
14+
## Metadata
15+
16+
```yaml
17+
Version : 0.1.0
18+
Kind : resource
19+
Tags : [Windows]
20+
Author : Microsoft
21+
```
22+
23+
## Instance definition syntax
24+
25+
```yaml
26+
resources:
27+
- name: <instanceName>
28+
type: Microsoft.Windows/WindowsPowerShell
29+
properties:
30+
resources:
31+
- name: <instanceName>
32+
type: <moduleName>/<resourceName>
33+
properties:
34+
# Instance properties
35+
Ensure: Present
36+
37+
# Or from v3.1.0-preview.2 onwards
38+
resources:
39+
- name: <instanceName>
40+
type: <moduleName>/<resourceName>
41+
properties:
42+
# Instance properties
43+
Ensure: Present
44+
```
45+
46+
## Description
47+
48+
The `Microsoft.Windows/WindowsPowerShell` resource adapter enables you to invoke PSDSC resources. The resource can:
49+
50+
- Execute script-based DSC resources
51+
- Run class-based DSC resource methods
52+
- Execute binary DSC resources
53+
54+
> [!NOTE]
55+
> This resource is installed with DSC itself on Windows systems.
56+
>
57+
> You can update this resource by updating DSC. When you update DSC, the updated version of this
58+
> resource is automatically available.
59+
60+
## Requirements
61+
62+
- The resource is only usable on a Windows system.
63+
- The resource must run in a process context that has appropriate permissions for the DSC resource to be executed.
64+
- The PowerShell modules exposing DSC resources should be installed in
65+
`%PROGRAMFILES%\WindowsPowerShell\Modules` or
66+
`%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules`
67+
68+
## Capabilities
69+
70+
The resource adapter has the following capabilities:
71+
72+
- `get` - You can use the resource to retrieve the actual state of a DSC resource instance.
73+
- `set` - You can use the resource to enforce the desired state for a DSC resource instance.
74+
- `test` - You can use the resource to determine whether a DSC resource instance is in the desired state.
75+
- `export` - You can use the resource to discover and enumerate DSC resource instances currently installed and available on the system.
76+
- `list` - Lists available PowerShell DSC resources on your system that can be used with `dsc.exe`.
77+
78+
> [!NOTE]
79+
> The `export` capability is only available with class-based DSC resources.
80+
> Script-based and binary DSC resources do not support the export operation.
81+
82+
## Examples
83+
84+
1. [Manage a Windows Service][01] - Shows how to manage a Windows service
85+
86+
## Properties
87+
88+
Unlike standard resources, the `Microsoft.Windows/WindowsPowerShell` resource adapter doesn't have directly exposed properties
89+
in its schema because it acts as a bridge to PowerShell DSC resource. Instead, the adapter:
90+
91+
1. Dynamically discovers the property schema for each PowerShell DSC resource
92+
2. Stores the schema properties in a cache file for improved performance in subsequent operations
93+
3. Passes properties to the underlying PowerShell DSC resource
94+
95+
The adapter maintains a cache of resource schemas at:
96+
97+
- Windows: `%LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json`
98+
99+
To list the schema properties for a PowerShell DSC resource, you can run the following command:
100+
101+
```powershell
102+
dsc resource list --adapter Microsoft.Windows/WindowsPowerShell <moduleName>/<resourceName> |
103+
ConvertFrom-Json |
104+
Select-Object properties
105+
```
106+
107+
You can also retrieve more information by directly reading it from the cache file:
108+
109+
```powershell
110+
$cache = Get-Content -Path "$env:LOCALAPPDATA\dsc\WindowsPSAdapterCache.json" |
111+
ConvertFrom-Json
112+
113+
($cache.ResourceCache | Where-Object -Property type -EQ '<moduleName>/<resourceName>').DscResourceInfo.Properties
114+
```
115+
116+
## Exit codes
117+
118+
The resource returns the following exit codes from operations:
119+
120+
- [0](#exit-code-0) - Success
121+
- [1](#exit-code-1) - Error
122+
123+
### Exit code 0
124+
125+
Indicates the resource operation completed without errors.
126+
127+
### Exit code 1
128+
129+
Indicates the resource operation failed because the underlying DSC resource method or Invoke-DscResource call did not succeed.
130+
When the resource returns this exit code, it also emits an error message with details about the failure.
131+
132+
<!-- Link definitions -->
133+
[01]: ./examples/manage-a-windows-service.md

0 commit comments

Comments
 (0)