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")
@@ -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()
@@ -463,6 +483,7 @@ Function Start-AsScheduledTask($common_functions, $script) {
                 blacklist = $blacklist
                 whitelist = $whitelist
                 check_mode = $check_mode
+                server_selection = $server_selection
             }
         )
         ErrorAction = "Stop"
@@ -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.