|
| 1 | +# Microsoft.Windows/UpdateList DSC Resource |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +The `Microsoft.Windows/UpdateList` resource enables querying information about Windows Updates using the Windows Update Agent COM APIs. This resource allows you to retrieve detailed information about specific updates available on or installed on a Windows system. |
| 6 | + |
| 7 | +## Features |
| 8 | + |
| 9 | +- Query Windows Update information by title |
| 10 | +- Retrieve comprehensive update details including: |
| 11 | + - Installation status |
| 12 | + - Update description |
| 13 | + - Unique update identifier |
| 14 | + - KB article IDs |
| 15 | + - Recommended hard disk space |
| 16 | + - Security severity rating |
| 17 | + - Security bulletin IDs |
| 18 | + - Update type (Software or Driver) |
| 19 | + |
| 20 | +## Requirements |
| 21 | + |
| 22 | +- Windows operating system |
| 23 | +- Windows Update Agent (built into Windows) |
| 24 | +- Administrator privileges may be required for certain update queries |
| 25 | + |
| 26 | +## Usage |
| 27 | + |
| 28 | +### Get Operation |
| 29 | + |
| 30 | +The `get` operation searches for a Windows Update by title or id (as exact match) and returns detailed information about the update. |
| 31 | + |
| 32 | +#### Input Schema |
| 33 | + |
| 34 | +```json |
| 35 | +{ |
| 36 | + "updates": [{ |
| 37 | + "title": "Security Update" |
| 38 | + }] |
| 39 | +} |
| 40 | +``` |
| 41 | + |
| 42 | +#### Example DSC Configuration |
| 43 | + |
| 44 | +```yaml |
| 45 | +# windows-update-query.dsc.yaml |
| 46 | +$schema: https://aka.ms/dsc/schemas/v3/configuration.json |
| 47 | +resources: |
| 48 | +- name: QuerySecurityUpdate |
| 49 | + type: Microsoft.Windows/UpdateList |
| 50 | + properties: |
| 51 | + updates: |
| 52 | + - title: "Security Update for Windows" |
| 53 | +``` |
| 54 | +
|
| 55 | +#### Output Example |
| 56 | +
|
| 57 | +```json |
| 58 | +{ |
| 59 | + "updates": [{ |
| 60 | + "title": "2024-01 Security Update for Windows 11 Version 22H2 for x64-based Systems (KB5034123)", |
| 61 | + "isInstalled": true, |
| 62 | + "description": "Install this update to resolve issues in Windows...", |
| 63 | + "id": "12345678-1234-1234-1234-123456789abc", |
| 64 | + "isUninstallable": true, |
| 65 | + "kbArticleIds": ["5034123"], |
| 66 | + "recommendedHardDiskSpace": 512, |
| 67 | + "msrcSeverity": "Critical", |
| 68 | + "securityBulletinIds": ["MS24-001"], |
| 69 | + "updateType": "Software" |
| 70 | + }] |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +## Properties |
| 75 | + |
| 76 | +### Input/Output Properties |
| 77 | + |
| 78 | +The resource returns an UpdateList object containing an array of updates: |
| 79 | + |
| 80 | +| Property | Type | Description | |
| 81 | +|-----------------------|-----------------|-------------------------------------------------------| |
| 82 | +| updates | array | Array of update objects | |
| 83 | +| updates[].title | string | The full title of the Windows Update | |
| 84 | +| updates[].isInstalled | boolean | Whether the update is currently installed | |
| 85 | +| updates[].description | string | Detailed description of the update | |
| 86 | +| updates[].id | string | Unique identifier (GUID) for the update | |
| 87 | +| updates[].isUninstallable | boolean | Whether the update can be uninstalled | |
| 88 | +| updates[].kbArticleIds | array[string] | Knowledge Base article identifiers | |
| 89 | +| updates[].recommendedHardDiskSpace | integer (int64) | Recommended hard disk space in megabytes (MB) | |
| 90 | +| updates[].msrcSeverity | enum | MSRC severity: Critical, Important, Moderate, or Low | |
| 91 | +| updates[].securityBulletinIds | array[string] | Security bulletin identifiers | |
| 92 | +| updates[].updateType | enum | Type of update: Software or Driver | |
| 93 | + |
| 94 | +## Implementation Details |
| 95 | + |
| 96 | +- **Language**: Rust |
| 97 | +- **Executable**: `wu_dsc` |
| 98 | +- **COM APIs Used**: Windows Update Agent (WUA) COM interfaces |
| 99 | + - `IUpdateSession` |
| 100 | + - `IUpdateSearcher` |
| 101 | + - `IUpdateCollection` |
| 102 | + - `IUpdate` |
| 103 | + |
| 104 | +## Limitations |
| 105 | + |
| 106 | +- Requires Windows operating system |
| 107 | +- Search is case-insensitive and matches partial titles |
| 108 | + |
| 109 | +## Building |
| 110 | + |
| 111 | +To build the resource: |
| 112 | + |
| 113 | +```powershell |
| 114 | +cd resources/WindowsUpdate |
| 115 | +cargo build --release |
| 116 | +``` |
| 117 | + |
| 118 | +The compiled executable will be located at `target/release/wu_dsc.exe`. |
| 119 | + |
| 120 | +## Testing |
| 121 | + |
| 122 | +To test the resource manually: |
| 123 | + |
| 124 | +```powershell |
| 125 | +# Create input JSON |
| 126 | +$input = @{ updates = @(@{ title = "Security Update" }) } | ConvertTo-Json -Depth 3 |
| 127 | +
|
| 128 | +# Query for an update |
| 129 | +$input | .\wu_dsc.exe get |
| 130 | +``` |
| 131 | + |
| 132 | +## Error Handling |
| 133 | + |
| 134 | +The resource will return an error if: |
| 135 | +- No update matching the specified title is found |
| 136 | +- COM initialization fails |
| 137 | +- The Windows Update service is unavailable |
| 138 | +- Invalid input is provided |
| 139 | + |
| 140 | +## License |
| 141 | + |
| 142 | +Copyright (c) Microsoft Corporation. |
| 143 | +Licensed under the MIT License. |
0 commit comments