Windows Update module

[dotjesper]

Module proposal: windowsUpdate - Trigger Windows Update scan and download

Windows gecko is a desired state configuration tool, and the idea of a windowsUpdate module has come up - a module that could trigger a Windows Update scan, download, and optionally install security updates and/or feature updates as part of a Windows gecko configuration run.

The inspiration comes from the Windows Server Core sconfig utility, which provides a simple menu-driven interface to scan for and install updates, with options to filter by update category (e.g., security updates only, all updates).

Proposed functionality

The module would allow administrators to:

• Trigger a Windows Update scan for available updates
• Filter by update category: security updates, feature updates, or both
• Download and optionally install updates
• Control whether a restart is triggered after installation

A conceptual configuration could look something like this:

{
  "windowsUpdate": {
    "enabled": true,
    "dataset": [
      {
        "description": "Scan and install security updates",
        "category": "SecurityUpdates",
        "action": "Install",
        "restartBehavior": "NoRestart"
      },
      {
        "description": "Scan for feature updates only",
        "category": "FeatureUpdates",
        "action": "ScanOnly",
        "restartBehavior": "NoRestart"
      }
    ]
  }
}

PowerShell approaches for triggering Windows Update

There are several ways to interact with Windows Update from PowerShell 5.1. Below are examples of the most common approaches.

Approach 1: COM-based Windows Update Agent API

This is the most direct approach using the Windows Update Agent (WUA) COM objects, and it does not require any additional modules.

# Create the Windows Update Session
$updateSession = New-Object -ComObject Microsoft.Update.Session
$updateSearcher = $updateSession.CreateUpdateSearcher()

# Search for security updates only (not installed)
$searchResult = $updateSearcher.Search("IsInstalled=0 AND Type='Software' AND CategoryIDs contains 'E6CF1350-C01B-414D-A61F-263D14D133B4'")
# Note: E6CF1350-C01B-414D-A61F-263D14D133B4 is the CategoryID for Security Updates

# Search for all available updates (not installed)
$searchResult = $updateSearcher.Search("IsInstalled=0")

Write-Host "Found $($searchResult.Updates.Count) updates available."

foreach ($update in $searchResult.Updates) {
    Write-Host "  - $($update.Title)"
}

# Download updates
$updatesToDownload = New-Object -ComObject Microsoft.Update.UpdateColl
foreach ($update in $searchResult.Updates) {
    if (-not $update.IsDownloaded) {
        $updatesToDownload.Add($update) | Out-Null
    }
}

if ($updatesToDownload.Count -gt 0) {
    $downloader = $updateSession.CreateUpdateDownloader()
    $downloader.Updates = $updatesToDownload
    $downloadResult = $downloader.Download()
    # ResultCode: 2 = Succeeded, 3 = Succeeded with errors, 4 = Failed, 5 = Aborted
    Write-Host "Download result: $($downloadResult.ResultCode)"
}

# Install updates
$updatesToInstall = New-Object -ComObject Microsoft.Update.UpdateColl
foreach ($update in $searchResult.Updates) {
    if ($update.IsDownloaded) {
        $updatesToInstall.Add($update) | Out-Null
    }
}

if ($updatesToInstall.Count -gt 0) {
    $installer = $updateSession.CreateUpdateInstaller()
    $installer.Updates = $updatesToInstall
    $installResult = $installer.Install()
    Write-Host "Install result: $($installResult.ResultCode)"
    Write-Host "Reboot required: $($installResult.RebootRequired)"
}

Approach 2: PSWindowsUpdate module

The PSWindowsUpdate PowerShell module from the PowerShell Gallery provides a more user-friendly interface, but requires module installation.

# Install the module (requires internet access)
Install-Module -Name PSWindowsUpdate -Force -Scope CurrentUser

# Scan for all available updates
Get-WindowsUpdate

# Scan for security updates only
Get-WindowsUpdate -Category "Security Updates"

# Download and install security updates without restarting
Install-WindowsUpdate -Category "Security Updates" -AcceptAll -IgnoreReboot

# Download and install all updates without restarting
Install-WindowsUpdate -AcceptAll -IgnoreReboot

# Download and install all updates and allow restart
Install-WindowsUpdate -AcceptAll -AutoReboot

Approach 3: USOClient (Update Session Orchestrator)

A lightweight approach that triggers the built-in Update Session Orchestrator.

# Start scan for updates
Start-Process -FilePath "USOClient.exe" -ArgumentList "StartScan" -Wait

# Start download of available updates
Start-Process -FilePath "USOClient.exe" -ArgumentList "StartDownload" -Wait

# Start install of downloaded updates
Start-Process -FilePath "USOClient.exe" -ArgumentList "StartInstall" -Wait

# Scan, download, and install
Start-Process -FilePath "USOClient.exe" -ArgumentList "ScanInstallWait" -Wait

Note

USOClient.exe provides no output or feedback. There is no way to determine what was scanned, downloaded, or installed, and no way to filter by update category. It is essentially a fire-and-forget approach.

Approach 4: Windows Update WMI provider

Available in newer Windows versions via the MDM Bridge WMI Provider.

# Trigger update scan via WMI (SYSTEM context required)
$AutoUpdate = (New-Object -ComObject Microsoft.Update.AutoUpdate)
$AutoUpdate.DetectNow()

# Or via the MDM WMI bridge (requires SYSTEM context)
$scanResult = Invoke-CimMethod -Namespace "root/cimv2/mdm/dmmap" `
    -ClassName "MDM_EnterpriseModernAppManagement_AppManagement01" `
    -MethodName "UpdateScanMethod"

Related resources

• Windows Update Agent API
• PSWindowsUpdate module
• Windows Autopatch overview
• Windows Update for Business
• sconfig - Server Configuration tool

[dotjesper]

Concerns and challenges

1. Execution time

Windows Update scans and installations can take anywhere from a few minutes to well over an hour, depending on the number and size of updates. This could make Windows gecko run significantly longer than expected, especially in deployment scenarios where execution time is critical (e.g., Windows Autopilot ESP phase). A 2-minute Windows gecko run that suddenly takes 45 minutes because of a cumulative update download would be unacceptable in most deployment scenarios.

2. Restart conflicts

Triggering an update scan and download without enforcing a restart introduces complexity. If updates are installed but a restart is deferred, the device is left in a pending-reboot state. This can conflict with:

• Other Windows gecko modules running after windowsUpdate
• Post-deployment configuration applied by Microsoft Intune
• The Enrollment Status Page (ESP) waiting for policy application
• Other scripts or applications that check for pending reboots

3. Synchronous vs. asynchronous execution

If Windows gecko waits for the update process to finish, execution time becomes unpredictable. If Windows gecko does not wait, the update process runs in the background and may conflict with other operations - registry changes, feature installations, or app deployments happening simultaneously. Neither option is ideal.

4. Timing and policy conflicts

In a Windows Autopilot deployment, Windows gecko typically runs early in the provisioning process. Triggering an update scan at this stage may happen before Windows Update policies are applied:

• Windows Autopatch policies may not yet be targeted or applied
• Windows Update for Business deferral policies from Microsoft Intune may not have taken effect
• WSUS or update ring configurations may not be in place

This could result in the device downloading and installing updates that should have been deferred, blocked, or managed by a specific update ring - leading to undesired behavior and potentially breaking the intended update management strategy.

5. Accidental feature update installation

This is perhaps the most critical concern. Without proper filtering or policy guardrails in place, triggering a Windows Update scan could inadvertently discover, download, and install a Windows 11 feature update - for example, upgrading a device from Windows 11 24H2 to 26H2. In a managed environment, feature update rollouts are carefully orchestrated through Windows Autopatch or Windows Update for Business deferral policies, controlling exactly when and which devices receive a new feature update.

If Windows gecko triggers an update scan before these policies are applied - or if the scan bypasses policy because it runs outside the normal Windows Update orchestration - the device could:

• Upgrade to a feature update that is not yet approved for the organization, skipping the intended rollout ring or pilot phase
• Override Windows Autopatch safeguard holds that are specifically designed to prevent known-issue feature updates from reaching production devices
• Install a feature update with breaking changes for line-of-business applications that have not yet been validated against the new version
• Create version fragmentation where some devices in the same deployment wave end up on different Windows 11 versions, complicating support and compliance reporting

This risk applies not only to feature updates but also to preview or optional updates that may appear in a scan result. The COM-based and PSWindowsUpdate approaches both accept all available updates by default unless explicitly filtered - and even with filtering, ensuring the correct category exclusions are maintained across Windows releases adds ongoing maintenance burden.

In short, an uncontrolled update scan initiated by Windows gecko could silently undermine the entire Windows update management strategy.

6. Constrained Language Mode compatibility

The COM-based approach (Microsoft.Update.Session) relies heavily on COM object instantiation and method calls that may not work reliably under PowerShell Constrained Language Mode (CLM). The PSWindowsUpdate module is not an option either, as it would require module installation and may use constructs not permitted under CLM. The USOClient approach works under CLM but provides no feedback or filtering capability.

7. Error handling and reporting

Windows Update operations can fail silently or produce errors that are difficult to interpret programmatically. Providing meaningful logging and error reporting within Windows gecko's CMTrace-compatible log format would be challenging, especially with the fire-and-forget approaches.

Intermediate conclusion

After evaluating the functionality, implementation approaches, and the challenges outlined above, the intermediate conclusion is that a windowsUpdate module is outside the scope of Windows gecko.

Windows gecko is a desired state configuration tool - it sets sensible defaults and baselines quickly and predictably. Windows Update management is fundamentally different: it involves unpredictable execution times, external dependencies (update servers, bandwidth, content), restart orchestration, and tight integration with management policies like Windows Update for Business / Windows Autopatch.

Adding update management to Windows gecko would:

• Violate the design philosophy - Windows gecko should execute quickly and predictably, applying configuration baselines without side effects that affect device availability or deployment timing.
• Overlap with purpose-built solutions - Microsoft Intune, Windows Update for Business, and Windows Autopatch already provide comprehensive, policy-driven update management with deferral rings, compliance reporting, and restart scheduling. Duplicating this in Windows gecko adds complexity without meaningful benefit.
• Introduce risk in deployment scenarios - triggering updates during Windows Autopilot provisioning, before update policies are applied, could undermine the intended update management strategy.
• Risk accidental feature update installation - an uncontrolled scan could discover and install a feature update (e.g., Windows 11 26H2) before Windows Autopatch or Windows Update for Business deferral policies are in effect, silently overriding the organization's update management strategy.

Windows Update management is best left to the dedicated management stack (Microsoft Intune + Windows Update for Business / Windows Autopatch), where it can be controlled through policy, monitored for compliance, and orchestrated with proper restart management.

This discussion remains open for community input. If there are scenarios where the above approach does not work, or if Microsoft introduces new APIs that address the timing and policy challenges, this decision can be revisited.

If there is a specific need to trigger an update scan as a final step after provisioning, this is better handled as a standalone script deployed separately via Microsoft Intune - outside of the Windows gecko execution context - where timing and sequencing can be controlled independently.