diff --git a/docs/reference/resources/Microsoft/Windows/WMI/examples/logicaldisk.config.dsc.yaml b/docs/reference/resources/Microsoft/Windows/WMI/examples/logicaldisk.config.dsc.yaml new file mode 100644 index 000000000..d0a4bfd4b --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/WMI/examples/logicaldisk.config.dsc.yaml @@ -0,0 +1,9 @@ +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: List logical disk information + type: root.cimv2/Win32_LogicalDisk + properties: + Name: + Description: + Status: diff --git a/docs/reference/resources/Microsoft/Windows/WMI/examples/query-filtered-disk-info.md b/docs/reference/resources/Microsoft/Windows/WMI/examples/query-filtered-disk-info.md new file mode 100644 index 000000000..5e4fd9d46 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/WMI/examples/query-filtered-disk-info.md @@ -0,0 +1,120 @@ +--- +description: > + Example showing how to use the Microsoft.Windows/WMI resource adapter to query + disk information with filtering using the Win32_LogicalDisk class. + +ms.date: 03/25/2025 +ms.topic: reference +title: Query filtered disk information using WMI adapter +--- + +This example demonstrates how to use the `Microsoft.Windows/WMI` resource adapter to query disk +information from a computer using the Win32_LogicalDisk WMI class with filtering to get only +specific drives using a configuration document. + +## Definition + +The configuration document for this example defines one instances of the `Win32_LogicalDisk` resource. + +The instance defines the properties to return in the output. + +:::code language="yaml" source="logicaldisk.config.dsc.yaml"::: + +Copy the configuration document and save it as `logicaldisk.config.dsc.yaml`. + +Before using the [dsc config get][01] command, the following section illustrates how you +can retrieve the available `Win32_LogicalDisk` properties. + +## List available disk properties + +To list out only the `Win32_LogicalDisk` WMI class, you can run the following command: + +```powershell +dsc resource list --adapter Microsoft.Windows/WMI root.cimv2/Win32_LogicalDisk | +ConvertFrom-Json | +Select-Object -ExpandProperty properties +``` + +DSC returns the following information: + +```text +Caption +Description +InstallDate +Name +Status +Availability +ConfigManagerErrorCode +ConfigManagerUserConfig +CreationClassName +DeviceID +ErrorCleared +ErrorDescription +LastErrorCode +PNPDeviceID +PowerManagementCapabilities +PowerManagementSupported +StatusInfo +SystemCreationClassName +SystemName +Access +BlockSize +ErrorMethodology +NumberOfBlocks +Purpose +FreeSpace +Size +Compressed +DriveType +FileSystem +MaximumComponentLength +MediaType +ProviderName +QuotasDisabled +QuotasIncomplete +QuotasRebuilding +SupportsDiskQuotas +SupportsFileBasedCompression +VolumeDirty +VolumeName +VolumeSerialNumber +``` + +## Query disk information with filtering + +To retrieve disk information with filtering, you can create a configuration file in YAML format and use it +with the `dsc config get` command. + +```powershell +dsc config get --file ./logicaldisk.config.dsc.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.1.0 + operation: get + executionType: actual + startDatetime: 2025-06-21T15:17:44.158969400+02:00 + endDatetime: 2025-06-21T15:17:54.213683700+02:00 + duration: PT10.0547143S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT5.9959229S + name: List logical disk information + type: root.cimv2/Win32_LogicalDisk + result: + actualState: + Description: Local Fixed Disk + Name: 'C:' + Status: null +messages: [] +hadErrors: false +``` + +This configuration will return only the specified properties for each fixed disk. + + +[01]: ../../../../../cli/config/get.md \ No newline at end of file diff --git a/docs/reference/resources/Microsoft/Windows/WMI/examples/query-operating-system-info.md b/docs/reference/resources/Microsoft/Windows/WMI/examples/query-operating-system-info.md new file mode 100644 index 000000000..24d843430 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/WMI/examples/query-operating-system-info.md @@ -0,0 +1,48 @@ +--- +description: > + Example showing how to use the Microsoft.Windows/WMI resource adapter to query + system information using the Win32_ComputerSystem class. + +ms.date: 03/25/2025 +ms.topic: reference +title: Query system information using WMI adapter +--- + +This example demonstrates how to use the `Microsoft.Windows/WMI` resource adapter +to query basic system information from a computer using the Win32_ComputerSystem WMI class. + +## List available system properties + +First, you can discover the available properties for the Win32_ComputerSystem class by running: + +```powershell +dsc resource list --adapter Microsoft.Windows/WMI +``` + +To list out only one WMI class, you can run the follwoing command: + +```powershell +dsc resource list --adapter Microsoft.Windows/WMI root.cimv2/Win32_ComputerSystem +``` + +DSC returns the following information: + +```text +Type Kind Version Capabilities RequireAdapter Description +---------------------------------------------------------------------------------------------------- +root.cimv2/Win32_ComputerSystem Resource gs--t--- Microsoft.Windows/WMI +``` + +## Query the operating system info + +To retrieve basic system information, the following snippets shows how you can use the resource +with [dsc resource get][01] command: + +```powershell +dsc resource get --resource root.cimv2/Win32_ComputerSystem +``` + +This command returns a JSON object containing information about the computer system. + + +[01]: ../../../../../cli/resource/get.md diff --git a/docs/reference/resources/Microsoft/Windows/WMI/index.md b/docs/reference/resources/Microsoft/Windows/WMI/index.md index e69de29bb..e55a98e6b 100644 --- a/docs/reference/resources/Microsoft/Windows/WMI/index.md +++ b/docs/reference/resources/Microsoft/Windows/WMI/index.md @@ -0,0 +1,192 @@ +--- +description: Microsoft.Windows/WMI resource adapter reference documentation +ms.date: 03/25/2025 +ms.topic: reference +title: Microsoft.Windows/WMI +--- + +# Microsoft.Windows/WMI + +## Synopsis + +Adapter for querying and retrieving information from Windows Management Instrumentation (WMI). + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [windows, wmi] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.Windows/WMI + properties: + # Required properties + resources: + - name: + type: / + properties: # adapted resource properties + +# Or from v3.1.0-preview.2 onwards +resources: +- name: + type: / + properties: # adapted resource properties + +``` + +## Description + +The `Microsoft.Windows/WMI` resource adapter enables you to query and retrieve information +from Windows Management Instrumentation (WMI). The resource can: + +- Execute WMI queries to retrieve system information +- Filter WMI query results based on specific conditions +- Access data from different WMI namespaces + +The adapter leverages PowerShell commands to retrieve and list information of WMI classes. + +## Requirements + +- The resource is only usable on a Windows system. +- The resource must run in a process context that has appropriate permissions to access WMI. + +## Capabilities + +The resource adapter has the following capabilities: + +- `get` - You can use the resource to retrieve information from WMI. +- `list` - Lists available WMI classes that can be queried. + +## Examples + +1. [Query Operating System Information][01] - Shows how to query basic operating system information +2. [Query Filtered Disk Information][02] - Shows how to query disk drives with filtering + +## Properties + +## Property schema + +WMI properties aren't exposed directly to a schema. To discover the available properties for a WMI class that you +can use in your configuration, run the following PowerShell command: + +```powershell +dsc resource list --adapter Microsoft.Windows/WMI / | + ConvertFrom-Json | + Select-Object properties +``` + +When defining a configuration document, the following properties are required. + +### resources + +The `resources` property defines a list of adapted WMI class instances that the adapter manages. +Every instance in the list must be unique, but instances may share the same DSC resource type. + +For more information about defining a valid adapted resource instance, see the +[Adapted resource instances](#adapted-resource-instances) section of this document. + +```yaml +Type: array +Required: true +MinimumItemCount: 1 +ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.resource.json +``` + +## Adapted resource instances + +Adapted resources instances always adhere to the +[DSC Configuration document resource instance schema](../../../../schemas/config/resource.md). + +Every adapted instance must be an object that defines the [name](#adapted-instance-name), +[type](#adapted-instance-type), and [properties](#adapted-instance-properties) for the instance. + +### Adapted instance name + +The `name` property of the adapted resource instance defines the short, human-readable name for the +instance. The adapted instance name must be a non-empty string containing only letters, numbers, +and spaces. This property should be unique within the adapter's `resources` array. + +> ![NOTE] +> The adapter doesn't currently raise an error when you define two adapted instances with the same +> name. In a future release, the adapter will be updated to emit a warning when adapted instances +> share the same name. In the next major version of the adapter, name conflicts will raise an +> error. +> +> Using the same name for multiple instances can make debugging and reviewing output more +> difficult. Always use unique names for every instance. + +```yaml +PropertyName: name +Type: string +Required: true +MinimumLength: 1 +Pattern: ^[a-zA-Z0-9 ]+$ +``` + +### Adapted instance type + +The `type` property identifies the adapted instance's WMI class resource. The value for this property +must be the valid fully qualified type name for the resource. + +This adapter uses the following syntax for determining the fully qualified type name of a WMI class: + +```Syntax +/ +``` + +For example, if a WMI class named `Win32_OperatingSystem`, the fully qualified type name for that +resource is `root.cimv2/Win32_OperatingSystem`. + +For more information about type names in DSC, see +[DSC Resource fully qualified type name schema reference][03]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### Adapted instance properties + +The `properties` of an adapted resource instance define its desired state. The value of this +property must be an object. In case of the WMI adapter resource, properties are added at runtime +when the adapter tries to execute. + +Each name for each property returns the filtered state. The property name isn't case sensitive. + +[!NOTE] +> The current WMI adapter doesn't warn or raise an error when an invalid property is passed. + + +```yaml +Type: object +Required: true +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Error + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed because the WMI query could not be executed successfully. +When the resource returns this exit code, it also emits an error message with details about the failure. + + +[01]: ./examples/query-operating-system-info.md +[02]: ./examples/query-filtered-disk-info.md +[03]: ../../../../schemas/config/type.md \ No newline at end of file diff --git a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md index e27e09fbb..026724e41 100644 --- a/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md +++ b/docs/reference/resources/Microsoft/Windows/WindowsPowerShell/index.md @@ -48,7 +48,7 @@ The `Microsoft.Windows/WindowsPowerShell` resource adapter enables you to invoke - Run class-based DSC resource methods - Execute binary DSC resources -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. +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. 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`