Skip to content

Commit 05f00db

Browse files
michaeltlombardimichaeltlombardi
authored
Merge pull request #900 from Gijsreyn/reference-doc-wmi
Reference doc for WMI adapter
2 parents 37b1b4b + 320ba20 commit 05f00db

File tree

6 files changed

+370
-9
lines changed

6 files changed

+370
-9
lines changed

‎docs/overview.md

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -86,14 +86,6 @@ To install DSC on any platform:
8686
1. Expand the release archive.
8787
1. Add the folder containing the expanded archive contents to the `PATH`.
8888

89-
> [!NOTE]
90-
> When downloading the latest release on Windows platform, make sure after extraction,
91-
> the files are unblocked. You can do this using the following PowerShell command:
92-
>
93-
> ```powershell
94-
> Get-ChildItem -Path <path-to-expanded-folder> -Recurse | Unblock-File
95-
> ```
96-
9789
### Install DSC on Windows with WinGet
9890

9991
The following commands can be used to install DSC using the published `winget` packages:

‎docs/reference/resources/Microsoft/Windows/WMI/examples/logicaldisk.config.dsc.yaml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
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: List logical disk information
5+
type: root.cimv2/Win32_LogicalDisk
6+
properties:
7+
Name:
8+
Description:
9+
Status:

‎docs/reference/resources/Microsoft/Windows/WMI/examples/query-filtered-disk-info.md

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
description: >
3+
Example showing how to use the Microsoft.Windows/WMI resource adapter to query
4+
disk information with filtering using the Win32_LogicalDisk class.
5+
6+
ms.date: 03/25/2025
7+
ms.topic: reference
8+
title: Query filtered disk information using WMI adapter
9+
---
10+
11+
This example demonstrates how to use the `Microsoft.Windows/WMI` resource adapter to query disk
12+
information from a computer using the Win32_LogicalDisk WMI class with filtering to get only
13+
specific drives using a configuration document.
14+
15+
## Definition
16+
17+
The configuration document for this example defines one instances of the `Win32_LogicalDisk` resource.
18+
19+
The instance defines the properties to return in the output.
20+
21+
:::code language="yaml" source="logicaldisk.config.dsc.yaml":::
22+
23+
Copy the configuration document and save it as `logicaldisk.config.dsc.yaml`.
24+
25+
Before using the [dsc config get][01] command, the following section illustrates how you
26+
can retrieve the available `Win32_LogicalDisk` properties.
27+
28+
## List available disk properties
29+
30+
To list out only the `Win32_LogicalDisk` WMI class, you can run the following command:
31+
32+
```powershell
33+
dsc resource list --adapter Microsoft.Windows/WMI root.cimv2/Win32_LogicalDisk |
34+
ConvertFrom-Json |
35+
Select-Object -ExpandProperty properties
36+
```
37+
38+
DSC returns the following information:
39+
40+
```text
41+
Caption
42+
Description
43+
InstallDate
44+
Name
45+
Status
46+
Availability
47+
ConfigManagerErrorCode
48+
ConfigManagerUserConfig
49+
CreationClassName
50+
DeviceID
51+
ErrorCleared
52+
ErrorDescription
53+
LastErrorCode
54+
PNPDeviceID
55+
PowerManagementCapabilities
56+
PowerManagementSupported
57+
StatusInfo
58+
SystemCreationClassName
59+
SystemName
60+
Access
61+
BlockSize
62+
ErrorMethodology
63+
NumberOfBlocks
64+
Purpose
65+
FreeSpace
66+
Size
67+
Compressed
68+
DriveType
69+
FileSystem
70+
MaximumComponentLength
71+
MediaType
72+
ProviderName
73+
QuotasDisabled
74+
QuotasIncomplete
75+
QuotasRebuilding
76+
SupportsDiskQuotas
77+
SupportsFileBasedCompression
78+
VolumeDirty
79+
VolumeName
80+
VolumeSerialNumber
81+
```
82+
83+
## Query disk information with filtering
84+
85+
To retrieve disk information with filtering, you can create a configuration file in YAML format and use it
86+
with the `dsc config get` command.
87+
88+
```powershell
89+
dsc config get --file ./logicaldisk.config.dsc.yaml
90+
```
91+
92+
```yaml
93+
metadata:
94+
Microsoft.DSC:
95+
version: 3.1.0
96+
operation: get
97+
executionType: actual
98+
startDatetime: 2025-06-21T15:17:44.158969400+02:00
99+
endDatetime: 2025-06-21T15:17:54.213683700+02:00
100+
duration: PT10.0547143S
101+
securityContext: restricted
102+
results:
103+
- metadata:
104+
Microsoft.DSC:
105+
duration: PT5.9959229S
106+
name: List logical disk information
107+
type: root.cimv2/Win32_LogicalDisk
108+
result:
109+
actualState:
110+
Description: Local Fixed Disk
111+
Name: 'C:'
112+
Status: null
113+
messages: []
114+
hadErrors: false
115+
```
116+
117+
This configuration will return only the specified properties for each fixed disk.
118+
119+
<!-- Link reference definitions -->
120+
[01]: ../../../../../cli/config/get.md

‎docs/reference/resources/Microsoft/Windows/WMI/examples/query-operating-system-info.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
description: >
3+
Example showing how to use the Microsoft.Windows/WMI resource adapter to query
4+
system information using the Win32_ComputerSystem class.
5+
6+
ms.date: 03/25/2025
7+
ms.topic: reference
8+
title: Query system information using WMI adapter
9+
---
10+
11+
This example demonstrates how to use the `Microsoft.Windows/WMI` resource adapter
12+
to query basic system information from a computer using the Win32_ComputerSystem WMI class.
13+
14+
## List available system properties
15+
16+
First, you can discover the available properties for the Win32_ComputerSystem class by running:
17+
18+
```powershell
19+
dsc resource list --adapter Microsoft.Windows/WMI
20+
```
21+
22+
To list out only one WMI class, you can run the follwoing command:
23+
24+
```powershell
25+
dsc resource list --adapter Microsoft.Windows/WMI root.cimv2/Win32_ComputerSystem
26+
```
27+
28+
DSC returns the following information:
29+
30+
```text
31+
Type Kind Version Capabilities RequireAdapter Description
32+
----------------------------------------------------------------------------------------------------
33+
root.cimv2/Win32_ComputerSystem Resource gs--t--- Microsoft.Windows/WMI
34+
```
35+
36+
## Query the operating system info
37+
38+
To retrieve basic system information, the following snippets shows how you can use the resource
39+
with [dsc resource get][01] command:
40+
41+
```powershell
42+
dsc resource get --resource root.cimv2/Win32_ComputerSystem
43+
```
44+
45+
This command returns a JSON object containing information about the computer system.
46+
47+
<!-- Link reference definitions -->
48+
[01]: ../../../../../cli/resource/get.md

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

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
---
2+
description: Microsoft.Windows/WMI resource adapter reference documentation
3+
ms.date: 03/25/2025
4+
ms.topic: reference
5+
title: Microsoft.Windows/WMI
6+
---
7+
8+
# Microsoft.Windows/WMI
9+
10+
## Synopsis
11+
12+
Adapter for querying and retrieving information from Windows Management Instrumentation (WMI).
13+
14+
## Metadata
15+
16+
```yaml
17+
Version : 0.1.0
18+
Kind : resource
19+
Tags : [windows, wmi]
20+
Author : Microsoft
21+
```
22+
23+
## Instance definition syntax
24+
25+
```yaml
26+
resources:
27+
- name: <instanceName>
28+
type: Microsoft.Windows/WMI
29+
properties:
30+
# Required properties
31+
resources:
32+
- name: <nested instance name>
33+
type: <namespace name>/<class name>
34+
properties: # adapted resource properties
35+
36+
# Or from v3.1.0-preview.2 onwards
37+
resources:
38+
- name: <instanceName>
39+
type: <namespace name>/<class name>
40+
properties: # adapted resource properties
41+
42+
```
43+
44+
## Description
45+
46+
The `Microsoft.Windows/WMI` resource adapter enables you to query and retrieve information
47+
from Windows Management Instrumentation (WMI). The resource can:
48+
49+
- Execute WMI queries to retrieve system information
50+
- Filter WMI query results based on specific conditions
51+
- Access data from different WMI namespaces
52+
53+
The adapter leverages PowerShell commands to retrieve and list information of WMI classes.
54+
55+
## Requirements
56+
57+
- The resource is only usable on a Windows system.
58+
- The resource must run in a process context that has appropriate permissions to access WMI.
59+
60+
## Capabilities
61+
62+
The resource adapter has the following capabilities:
63+
64+
- `get` - You can use the resource to retrieve information from WMI.
65+
- `list` - Lists available WMI classes that can be queried.
66+
67+
## Examples
68+
69+
1. [Query Operating System Information][01] - Shows how to query basic operating system information
70+
2. [Query Filtered Disk Information][02] - Shows how to query disk drives with filtering
71+
72+
## Properties
73+
74+
## Property schema
75+
76+
WMI properties aren't exposed directly to a schema. To discover the available properties for a WMI class that you
77+
can use in your configuration, run the following PowerShell command:
78+
79+
```powershell
80+
dsc resource list --adapter Microsoft.Windows/WMI <namespace name>/<class name> |
81+
ConvertFrom-Json |
82+
Select-Object properties
83+
```
84+
85+
When defining a configuration document, the following properties are required.
86+
87+
### resources
88+
89+
The `resources` property defines a list of adapted WMI class instances that the adapter manages.
90+
Every instance in the list must be unique, but instances may share the same DSC resource type.
91+
92+
For more information about defining a valid adapted resource instance, see the
93+
[Adapted resource instances](#adapted-resource-instances) section of this document.
94+
95+
```yaml
96+
Type: array
97+
Required: true
98+
MinimumItemCount: 1
99+
ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.resource.json
100+
```
101+
102+
## Adapted resource instances
103+
104+
Adapted resources instances always adhere to the
105+
[DSC Configuration document resource instance schema](../../../../schemas/config/resource.md).
106+
107+
Every adapted instance must be an object that defines the [name](#adapted-instance-name),
108+
[type](#adapted-instance-type), and [properties](#adapted-instance-properties) for the instance.
109+
110+
### Adapted instance name
111+
112+
The `name` property of the adapted resource instance defines the short, human-readable name for the
113+
instance. The adapted instance name must be a non-empty string containing only letters, numbers,
114+
and spaces. This property should be unique within the adapter's `resources` array.
115+
116+
> ![NOTE]
117+
> The adapter doesn't currently raise an error when you define two adapted instances with the same
118+
> name. In a future release, the adapter will be updated to emit a warning when adapted instances
119+
> share the same name. In the next major version of the adapter, name conflicts will raise an
120+
> error.
121+
>
122+
> Using the same name for multiple instances can make debugging and reviewing output more
123+
> difficult. Always use unique names for every instance.
124+
125+
```yaml
126+
PropertyName: name
127+
Type: string
128+
Required: true
129+
MinimumLength: 1
130+
Pattern: ^[a-zA-Z0-9 ]+$
131+
```
132+
133+
### Adapted instance type
134+
135+
The `type` property identifies the adapted instance's WMI class resource. The value for this property
136+
must be the valid fully qualified type name for the resource.
137+
138+
This adapter uses the following syntax for determining the fully qualified type name of a WMI class:
139+
140+
```Syntax
141+
<namespace name>/<class name>
142+
```
143+
144+
For example, if a WMI class named `Win32_OperatingSystem`, the fully qualified type name for that
145+
resource is `root.cimv2/Win32_OperatingSystem`.
146+
147+
For more information about type names in DSC, see
148+
[DSC Resource fully qualified type name schema reference][03].
149+
150+
```yaml
151+
Type: string
152+
Required: true
153+
Pattern: ^\w+(\.\w+){0,2}\/\w+$
154+
```
155+
156+
### Adapted instance properties
157+
158+
The `properties` of an adapted resource instance define its desired state. The value of this
159+
property must be an object. In case of the WMI adapter resource, properties are added at runtime
160+
when the adapter tries to execute.
161+
162+
Each name for each property returns the filtered state. The property name isn't case sensitive.
163+
164+
[!NOTE]
165+
> The current WMI adapter doesn't warn or raise an error when an invalid property is passed.
166+
167+
168+
```yaml
169+
Type: object
170+
Required: true
171+
```
172+
173+
## Exit codes
174+
175+
The resource returns the following exit codes from operations:
176+
177+
- [0](#exit-code-0) - Success
178+
- [1](#exit-code-1) - Error
179+
180+
### Exit code 0
181+
182+
Indicates the resource operation completed without errors.
183+
184+
### Exit code 1
185+
186+
Indicates the resource operation failed because the WMI query could not be executed successfully.
187+
When the resource returns this exit code, it also emits an error message with details about the failure.
188+
189+
<!-- Link definitions -->
190+
[01]: ./examples/query-operating-system-info.md
191+
[02]: ./examples/query-filtered-disk-info.md
192+
[03]: ../../../../schemas/config/type.md

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ The `Microsoft.Windows/WindowsPowerShell` resource adapter enables you to invoke
4848
- Run class-based DSC resource methods
4949
- Execute binary DSC resources
5050

51-
The adapter manages the PDSC resources in Windows PowerShell, not PowerShell. To use PowerShell classes in PowerShell, use the [Microsoft.DSC/PowerShell](../../dsc/powershell/index.md) adapter.
51+
The adapter manages the PSDSC resources in Windows PowerShell, not PowerShell. To use PowerShell classes in PowerShell, use the [Microsoft.DSC/PowerShell](../../dsc/powershell/index.md) adapter.
5252

5353
This adapter uses the **PSDesiredStateConfiguration** module v1.1. This module is built-in when you install Windows and is located in `%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules`
5454

0 commit comments

Comments
 (0)