win_say: Port to use CSharpUtil AnsibleBasic (#48361)

* port win-say to use CSharpUtil AnsibleBasic and add warning when requested voice not found

* win_say: fixes following code review: use C# style properties consistently; prefix changelog fragments

* fix invalid yaml in change log fragment

* win_say: fixes following code review: use generic module parameter validation where possible

* remove redundant setting of Result.changed to false, simplified some logic for readability.

* fix serialisation issue when message text is drawn from a file; allows tests to be run not in check mode and fix up some test descriptions

changelogs/fragments/win-say-ansible-basic.yaml

@@ -0,0 +1,4 @@
+minor_changes:
+ - win_say - Ported code to use Ansible.Basic.
+ - win_say - If requested voice is not found a warning is now displayed.
+ - win_say - Some error messages worded differently now that the module uses generic module parameter validation.

lib/ansible/modules/windows/win_say.ps1

@@ -3,58 +3,62 @@
 # Copyright: (c) 2016, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-#Requires -Module Ansible.ModuleUtils.Legacy
+#AnsibleRequires -CSharpUtil Ansible.Basic
 
-$params = Parse-Args $args -supports_check_mode $true
-$check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false
+$spec = @{
+   options = @{
+      msg = @{ type = "str"  }
+      msg_file = @{ type = "path"  }
+      start_sound_path = @{ type = "path"  }
+      end_sound_path = @{ type = "path"  }
+      voice = @{ type = "str"  }
+      speech_speed = @{ type = "int"; default = 0  }
+   }
+   mutually_exclusive = @(
+     ,@('msg', 'msg_file')
+   )
+   required_one_of = @(
+     ,@('msg', 'msg_file', 'start_sound_path', 'end_sound_path')
+   )
+   supports_check_mode = $true
+}
 
-$msg = Get-AnsibleParam -obj $params -name "msg" -type "str"
-$msg_file = Get-AnsibleParam -obj $params -name "msg_file" -type "path"
-$start_sound_path = Get-AnsibleParam -obj $params -name "start_sound_path" -type "path"
-$end_sound_path = Get-AnsibleParam -obj $params -name "end_sound_path" -type "path"
-$voice = Get-AnsibleParam -obj $params -name "voice" -type "str"
-$speech_speed = Get-AnsibleParam -obj $params -name "speech_speed" -type "int" -default 0
+$module = [Ansible.Basic.AnsibleModule]::Create($args, $spec)
 
-$result = @{
-    changed = $false
+
+$msg = $module.Params.msg
+$msg_file = $module.Params.msg_file
+$start_sound_path = $module.Params.start_sound_path
+$end_sound_path = $module.Params.end_sound_path
+$voice = $module.Params.voice
+$speech_speed = $module.Params.speech_speed
+
+if ($speech_speed -lt -10 -or $speech_speed -gt 10) {
+   $module.FailJson("speech_speed needs to be an integer in the range -10 to 10.  The value $speech_speed is outside this range.")
 }
 
 $words = $null
 
-if ($speech_speed -lt -10 -or $speech_speed -gt 10) {
-   Fail-Json $result "speech_speed needs to a integer in the range -10 to 10.  The value $speech_speed is outside this range."
-}
-
-if ($msg_file -and $msg) {
-   Fail-Json $result "Please specify either msg_file or msg parameters, not both"
-}
-
-if (-not $msg_file -and -not $msg -and -not $start_sound_path -and -not $end_sound_path) {
-   Fail-Json $result "No msg_file, msg, start_sound_path, or end_sound_path parameters have been specified.  Please specify at least one so the module has something to do"
-}
-
 if ($msg_file) {
-   if (Test-Path -Path $msg_file) {
+   if (-not (Test-Path -Path $msg_file)) {
+      $module.FailJson("Message file $msg_file could not be found or opened.  Ensure you have specified the full path to the file, and the ansible windows user has permission to read the file.")
+   } 
    $words = Get-Content $msg_file | Out-String
-   } else {
-      Fail-Json $result "Message file $msg_file could not be found or opened.  Ensure you have specified the full path to the file, and the ansible windows user has permission to read the file."
-   }
-}
-
-if ($start_sound_path) {
-   if (Test-Path -Path $start_sound_path) {
-      if (-not $check_mode) {
-         (new-object Media.SoundPlayer $start_sound_path).playSync()
-      }
-   } else {
-      Fail-Json $result "Start sound file $start_sound_path could not be found or opened.  Ensure you have specified the full path to the file, and the ansible windows user has permission to read the file."
-   }
 }
 
 if ($msg) {
    $words = $msg
 }
 
+if ($start_sound_path) {
+   if (-not (Test-Path -Path $start_sound_path)) {
+      $module.FailJson("Start sound file $start_sound_path could not be found or opened.  Ensure you have specified the full path to the file, and the ansible windows user has permission to read the file.")
+   } 
+   if (-not $module.CheckMode) {
+      (new-object Media.SoundPlayer $start_sound_path).playSync()
+   }
+}
+
 if ($words) {
    Add-Type -AssemblyName System.speech
    $tts = New-Object System.Speech.Synthesis.SpeechSynthesizer
@@ -62,30 +66,30 @@ if ($words) {
       try {
          $tts.SelectVoice($voice)
       } catch  [System.Management.Automation.MethodInvocationException] {
-         $result.voice_info = "Could not load voice $voice, using system default voice."
+         $module.Result.voice_info = "Could not load voice '$voice', using system default voice."
+         $module.Warn("Could not load voice '$voice', using system default voice.")
       }
    }
 
-   $result.voice = $tts.Voice.Name
+   $module.Result.voice = $tts.Voice.Name
    if ($speech_speed -ne 0) {
       $tts.Rate = $speech_speed
    }
-   if (-not $check_mode) {
+   if (-not $module.CheckMode) {
       $tts.Speak($words)
    }
    $tts.Dispose()
 }
 
 if ($end_sound_path) {
-   if (Test-Path -Path $end_sound_path) {
-      if (-not $check_mode) {
+   if (-not (Test-Path -Path $end_sound_path)) {
+      $module.FailJson("End sound file $start_sound_path could not be found or opened.  Ensure you have specified the full path to the file, and the ansible windows user has permission to read the file.")
+   } 
+   if (-not $module.CheckMode) {
       (new-object Media.SoundPlayer $end_sound_path).playSync()
    }
-   } else {
-      Fail-Json $result "End sound file $start_sound_path could not be found or opened.  Ensure you have specified the full path to the file, and the ansible windows user has permission to read the file."
-   }
 }
 
-$result.message_text = $words
+$module.Result.message_text = $words.ToString()
 
-Exit-Json $result
+$module.ExitJson()

test/integration/targets/win_say/tasks/main.yml

@@ -4,21 +4,21 @@
 - name: Warn of impending deployment
   win_say:
     msg: Warning, deployment commencing in 5 minutes, please log out.
-  check_mode: yes
+  check_mode: "{{ win_say_check_mode |default('yes') }}"
 
-- name: Using a different voice and a start sound
+- name: Using a specified voice and a start sound
   win_say:
     msg: Warning, deployment commencing in 5 minutes, please log out.
     start_sound_path: C:\Windows\Media\ding.wav
     voice: Microsoft Hazel Desktop
-  check_mode: yes
+  check_mode: "{{ win_say_check_mode |default('yes') }}"
 
 - name: Example with start and end sound
   win_say:
     msg: New software installed
     start_sound_path: C:\Windows\Media\Windows Balloon.wav
     end_sound_path: C:\Windows\Media\chimes.wav
-  check_mode: yes
+  check_mode: "{{ win_say_check_mode |default('yes') }}"
 
 - name: Create message file
   win_copy:
@@ -30,15 +30,15 @@
     msg_file: C:\Windows\Temp\win_say_message.txt
     start_sound_path: C:\Windows\Media\Windows Balloon.wav
     end_sound_path: C:\Windows\Media\chimes.wav
-  check_mode: yes
+  check_mode: "{{ win_say_check_mode |default('yes') }}"
 
 - name: Remove message file
   win_file:
     path: C:\Windows\Temp\win_say_message.txt
     state: absent
 
-- name: Different spech peed
+- name: Different speech speed
   win_say:
     speech_speed: 5
     msg: Stay calm and proceed to the closest fire exit.
-  check_mode: yes
+  check_mode: "{{ win_say_check_mode |default('yes') }}"