Added support for defining the ServerSelection attribute of the update searcher session, which allows specifying non-default update server sources. (#51334)

* Added support for defining the ServerSelection attribute of the update searcher session, which allows specifying non-default update server sources. This is useful if targeted systems have Windows Updates defaulted to WSUS or SCCM sources and we want to instead force searches to the online Windows Update catalog.

* fixed documentation formatting

* fixed documentation, added version_added info

* changed server_selection to a string value and refined documentation

* simplified parameter validation & result output, enhanced logging detail & documentation

lib/ansible/modules/windows/win_updates.ps1

@@ -16,6 +16,7 @@ $log_path = Get-AnsibleParam -obj $params -name "log_path" -type "path"
 $state = Get-AnsibleParam -obj $params -name "state" -type "str" -default "installed" -validateset "installed", "searched"
 $blacklist = Get-AnsibleParam -obj $params -name "blacklist" -type "list"
 $whitelist = Get-AnsibleParam -obj $params -name "whitelist" -type "list"
+$server_selection = Get-AnsibleParam -obj $params -name "server_selection" -type "string" -default "default" -validateset "default", "managed_server", "windows_update"
 
 # For backwards compatibility
 Function Get-CategoryMapping ($category_name) {
@@ -59,7 +60,8 @@ $update_script_block = {
             $log_path,
             $state,
             $blacklist,
-            $whitelist
+            $whitelist,
+            $server_selection
         )
 
         $result = @{
@@ -86,6 +88,23 @@ $update_script_block = {
             return $result
         }
 
+        Write-DebugLog -msg "Setting the Windows Update Agent source catalog..."
+        Write-DebugLog -msg "Requested search source is '$($server_selection)'"
+        try {
+            $server_selection_value = switch ($server_selection) {
+                "default" { 0 ; break }
+                "managed_server" { 1 ; break }
+                "windows_update" { 2 ; break }
+            }
+            $searcher.serverselection = $server_selection_value
+            Write-DebugLog -msg "Search source set to '$($server_selection)' (ServerSelection = $($server_selection_value))"
+        }
+        catch {
+            $result.failed = $true
+            $result.msg = "Failed to set Windows Update Agent search source: $($_.Exception.Message)"
+            return $result
+        }
+
         Write-DebugLog -msg "Searching for updates to install"
         try {
             $search_result = $searcher.Search("IsInstalled = 0")
@@ -219,7 +238,7 @@ $update_script_block = {
                 $result.msg = "A reboot is required before more updates can be installed"
                 return $result
             }
-            Write-DebugLog -msg "No reboot is pending..."    
+            Write-DebugLog -msg "No reboot is pending..."
         } else {
             # no updates to install exit here
             return $result
@@ -402,6 +421,7 @@ Function Start-Natively($common_functions, $script) {
             blacklist = $blacklist
             whitelist = $whitelist
             check_mode = $check_mode
+            server_selection = $server_selection
         }) > $null
 
         $output = $ps_pipeline.Invoke()
@@ -441,8 +461,8 @@ Function Remove-ScheduledJob($name) {
             $task_to_stop.Stop()
         }
 
-        <# FUTURE: add a global waithandle for this to release any other waiters. Wait-Job 
+        <# FUTURE: add a global waithandle for this to release any other waiters. Wait-Job
-        and/or polling will block forever, since the killed job object in the parent 
+        and/or polling will block forever, since the killed job object in the parent
         session doesn't know it's been killed :( #>
         Unregister-ScheduledJob -Name $name
     }
@@ -463,6 +483,7 @@ Function Start-AsScheduledTask($common_functions, $script) {
                 blacklist = $blacklist
                 whitelist = $whitelist
                 check_mode = $check_mode
+                server_selection = $server_selection
             }
         )
         ErrorAction = "Stop"
@@ -521,7 +542,7 @@ Function Start-AsScheduledTask($common_functions, $script) {
         $ret.Output = $job.Output.job_output # sub-object returned, can only be accessed as a property for some reason
     }
 
-    try { # this shouldn't be fatal, but can fail with both Powershell errors and COM Exceptions, hence the dual error-handling... 
+    try { # this shouldn't be fatal, but can fail with both Powershell errors and COM Exceptions, hence the dual error-handling...
         Unregister-ScheduledJob -Name $job_name -Force -ErrorAction Continue
     } catch {
         Write-DebugLog "Error unregistering job after execution: $($_.Exception.ToString()) $($_.ScriptStackTrace)"
@@ -560,4 +581,3 @@ if ($wua_available) {
 }
 
 Exit-Json -obj $result
-

lib/ansible/modules/windows/win_updates.py

@@ -58,6 +58,24 @@ options:
         - This is only used if C(reboot=yes) and a reboot is required.
         default: 1200
         version_added: '2.5'
+    server_selection:
+        description:
+        - Defines the Windows Update source catalog.
+        - C(default) Use the default search source. For many systems default is
+          set to the Microsoft Windows Update catalog. Systems participating in
+          Windows Server Update Services (WSUS), Systems Center Configuration
+          Manager (SCCM), or similar corporate update server environments may
+          default to those managed update sources instead of the Windows Update
+          catalog.
+        - C(managed_server) Use a managed server catalog. For environments
+          utilizing Windows Server Update Services (WSUS), Systems Center
+          Configuration Manager (SCCM), or similar corporate update servers, this
+          option selects the defined corporate update source.
+        - C(windows_update) Use the Microsoft Windows Update catalog.
+        type: str
+        choices: [ default, managed_server, windows_update ]
+        default: default
+        version_added: '2.8'
     state:
         description:
         - Controls whether found updates are returned as a list or actually installed.