Windows: A module for creating Toast notifications on Modern Windows versions. (#26675)

* replace duff commit version of win_toast

* change expire_mins to expire_secs and add example showing use of async

* fix metadata version to keep sanity --test validate-modules happy

* code review fixes and change expire_secs to expire_seconds

* add first pass integration tests for win_toast

* win_toast no longer fails if there are no logged in users to notify (it sets a toast_sent false if this happens)

* yaml lint clean up of setup.yml in win_toast integration tests

* improve exception and stack trace if the notifier cannot be created, following feedback from dag

* removed unwanted 'echo' input parameters from return vals; added to CHANGELOG.md, removed _seconds units from module params; updated tests to match

lib/ansible/modules/windows/win_toast.ps1

@@ -0,0 +1,91 @@
+#!powershell
+# This file is part of Ansible
+
+# Copyright (c) 2017, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+#Requires -Module Ansible.ModuleUtils.Legacy.psm1
+
+$ErrorActionPreference = "Stop"
+
+# version check
+$osversion = [Environment]::OSVersion
+$lowest_version = 10
+if ($osversion.Version.Major -lt $lowest_version ) {
+   Fail-Json $result "Sorry, this version of windows, $osversion, does not support Toast notifications.  Toast notifications are available from version $lowest_version" 
+}
+
+$stopwatch = [system.diagnostics.stopwatch]::startNew()
+$now = [DateTime]::Now
+$default_title = "Notification: " + $now.ToShortTimeString()
+
+$params = Parse-Args $args -supports_check_mode $true
+$check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false
+
+$expire_seconds = Get-AnsibleParam -obj $params -name "expire" -type "int" -default 45
+$group = Get-AnsibleParam -obj $params -name "group" -type "str" -default "Powershell"
+$msg = Get-AnsibleParam -obj $params -name "msg" -type "str" -default "Hello world!"
+$popup = Get-AnsibleParam -obj $params -name "popup" -type "bool" -default $true
+$tag = Get-AnsibleParam -obj $params -name "tag" -type "str" -default "Ansible"
+$title = Get-AnsibleParam -obj $params -name "title" -type "str" -default $default_title
+
+$timespan = New-TimeSpan -Seconds $expire_seconds
+$expire_at = $now + $timespan
+$expire_at_utc = $($expire_at.ToUniversalTime()|Out-String).Trim()
+
+$result = @{
+    changed = $false
+    expire_at = $expire_at.ToString()
+    expire_at_utc = $expire_at_utc
+    toast_sent = $false
+}
+
+# If no logged in users, there is no notifications service,
+# and no-one to read the message, so exit but do not fail
+# if there are no logged in users to notify.
+ 
+if ((get-process -name explorer -EA silentlyContinue).Count -gt 0){
+
+  [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null
+  $template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText01)
+  
+  #Convert to .NET type for XML manipulation
+  $toastXml = [xml] $template.GetXml()
+  $toastXml.GetElementsByTagName("text").AppendChild($toastXml.CreateTextNode($title)) > $null
+  # TODO add subtitle
+  
+  #Convert back to WinRT type
+  $xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+  $xml.LoadXml($toastXml.OuterXml)
+  
+  $toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
+  $toast.Tag = $tag
+  $toast.Group = $group
+  $toast.ExpirationTime = $expire_at
+  $toast.SuppressPopup = -not $popup
+  
+  try {
+     $notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($msg)
+     if (-not $check_mode) {
+        $notifier.Show($toast)
+        $result.toast_sent = $true
+        Start-Sleep -Seconds $expire_seconds
+     }
+  } catch {
+    $excep = $_
+    $result.exception = $excep.ScriptStackTrace
+    Fail-Json -obj $result -message "Failed to create toast notifier: $($excep.Exception.Message)"
+  }
+} else {
+   $result.toast_sent = $false
+   $result.no_toast_sent_reason = 'No logged in users to notifiy'
+}
+
+$endsend_at = Get-Date| Out-String
+$stopwatch.Stop()
+
+$result.time_taken = $stopwatch.Elapsed.TotalSeconds
+$result.sent_localtime = $endsend_at.Trim()
+  
+Exit-Json $result