win_msi: Add check_mode and removes options (#26086)

This PR includes:
- Add support for the removes option
- Add check_mode support (which does test MSI file, creates, removes)
- Simplify code

lib/ansible/modules/windows/win_msi.ps1

@@ -19,13 +19,13 @@
 # WANT_JSON
 # POWERSHELL_COMMON
 
-# TODO: Add check-mode support
-
-$params = Parse-Args $args
+$params = Parse-Args $args  -supports_check_mode $true
+$check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false
 
 $path = Get-AnsibleParam -obj $params -name "path" -type "path" -failifempty $true
-$state = Get-AnsibleParam -obj $params -name "state" -type "str" -default "present" -validateset "present","absent"
+$state = Get-AnsibleParam -obj $params -name "state" -type "str" -default "present" -validateset "absent","present"
 $creates = Get-AnsibleParam -obj $params -name "creates" -type "path"
+$removes = Get-AnsibleParam -obj $params -name "removes" -type "path"
 $extra_args = Get-AnsibleParam -obj $params -name "extra_args" -type "str" -default ""
 $wait = Get-AnsibleParam -obj $params -name "wait" -type "bool" -default $false
 
@@ -33,35 +33,31 @@ $result = @{
     changed = $false
 }
 
-if (($creates -ne $null) -and ($state -ne "absent") -and (Test-Path $creates)) {
-    Exit-Json $result
+if (-not (Test-Path -Path $path)) {
+    Fail-Json $result "The MSI file ($path) was not found."
 }
 
-if (-not (Test-Path $path)) {
-	Fail-Json $result "Cannot find $path."
+if ($creates -and (Test-Path -Path $creates)) {
+    Exit-Json $result "The 'creates' file or directory ($creates) already exists."
 }
 
-$logfile = [IO.Path]::GetTempFileName()
-if ($state -eq "absent") {
-
-    if ($wait) {
-        Start-Process -FilePath msiexec.exe -ArgumentList "/x `"$path`" /qn /l $logfile $extra_args" -Verb Runas -Wait
-    } else {
-        Start-Process -FilePath msiexec.exe -ArgumentList "/x `"$path`" /qn /l $logfile $extra_args" -Verb Runas
-    }
+if ($removes -and -not (Test-Path -Path $removes)) {
+    Exit-Json $result "The 'removes' file or directory ($removes) does not exist."
+}
 
-} else {
+if (-not $check_mode) {
 
-    if ($wait) {
-        Start-Process -FilePath msiexec.exe -ArgumentList "/i `"$path`" /qn /l $logfile $extra_args" -Verb Runas -Wait
+    $logfile = [IO.Path]::GetTempFileName()
+    if ($state -eq "absent") {
+        Start-Process -FilePath msiexec.exe -ArgumentList "/x `"$path`" /qn /log $logfile $extra_args" -Verb Runas -Wait:$wait
     } else {
-        Start-Process -FilePath msiexec.exe -ArgumentList "/i `"$path`" /qn /l $logfile $extra_args" -Verb Runas
+        Start-Process -FilePath msiexec.exe -ArgumentList "/i `"$path`" /qn /log $logfile $extra_args" -Verb Runas -Wait:$wait
     }
+    $result.log = Get-Content $logfile | Out-String
+    Remove-Item $logfile
 
 }
 
 $result.changed = $true
-$result.log = Get-Content $logfile | Out-String
-Remove-Item $logfile
 
 Exit-Json $result

lib/ansible/modules/windows/win_msi.py

@@ -25,15 +25,14 @@ ANSIBLE_METADATA = {'metadata_version': '1.0',
                     'status': ['deprecated'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_msi
-version_added: "1.7"
+version_added: '1.7'
 short_description: Installs and uninstalls Windows MSI files
 description:
     - Installs or uninstalls a Windows MSI file that is already located on the
-      target server
+      target server.
 options:
     path:
         description:
@@ -41,30 +40,33 @@ options:
         required: true
     extra_args:
         description:
-            - Additional arguments to pass to the msiexec.exe command
+            - Additional arguments to pass to the msiexec.exe command.
     state:
         description:
-            - Whether the MSI file should be installed or uninstalled
-        choices:
-            - present
-            - absent
+            - Whether the MSI file should be installed or uninstalled.
+        choices: [ absent, present ]
         default: present
     creates:
         description:
             - Path to a file created by installing the MSI to prevent from
-              attempting to reinstall the package on every run
+              attempting to reinstall the package on every run.
+    removes:
+        description:
+            - Path to a file removed by uninstalling the MSI to prevent from
+              attempting to re-uninstall the package on every run.
+        version_added: '2.4'
     wait:
-        version_added: "2.1"
         description:
             - Specify whether to wait for install or uninstall to complete before continuing.
-        choices:
-            - true
-            - false
-        default: false
+        type: bool
+        default: 'no'
+        version_added: '2.1'
 notes:
-- Check-mode support is currently not supported.
-- Please look into M(win_package) instead, this package will be deprecated in Ansible v2.3.
-author: "Matt Martz (@sivel)"
+- This module is not idempotent and will report a change every time.
+  Use the C(creates) and C(removes) options to your advantage.
+- Please look into M(win_package) instead, this package will be deprecated in the future.
+author:
+- Matt Martz (@sivel)
 '''
 
 EXAMPLES = r'''
@@ -75,10 +77,18 @@ EXAMPLES = r'''
 - name: Install an MSI, and wait for it to complete before continuing
   win_msi:
     path: C:\7z920-x64.msi
-    wait: true
+    wait: yes
 
 - name: Uninstall an MSI file
   win_msi:
     path: C:\7z920-x64.msi
     state: absent
 '''
+
+RETURN = r'''
+log:
+  description: The logged output from the installer
+  returned: always
+  type: string
+  sample: N/A
+'''