(#264) Add Urgent switch support to BurntToast cmdlets for important notifications

Add -Urgent switch to Submit-BTNotification and New-BurntToastNotification to designate toasts as "Important Notifications" that break through Focus Assist.

Fixes #264

Author: Windos

Help/New-BTContent.md

@@ -18,7 +18,7 @@ The `New-BTContent` function creates a new `ToastContent` object, the root confi
 | `Duration`       | Microsoft.Toolkit.Uwp.Notifications.ToastDuration| Enum. How long the toast notification is displayed (Short/Long).                                    | No        |
 | `Header`         | Microsoft.Toolkit.Uwp.Notifications.ToastHeader  | ToastHeader object, created via `New-BTHeader`, categorizing the toast in Action Center.            | No        |
 | `Launch`         | String                                          | Data passed to the activation context when a toast is clicked.                                      | No        |
-| `Scenario`       | Microsoft.Toolkit.Uwp.Notifications.ToastScenario| Enum. Tells Windows to treat the toast as an alarm, reminder, or more (`ToastScenario`).            | No        |
+| `Scenario`       | Microsoft.Toolkit.Uwp.Notifications.ToastScenario| Enum. Tells Windows to treat the toast as an alarm, reminder, or more (`ToastScenario`). Will be ignored if toast is submitted with `-Urgent` switch on the Submit-BTNotification function, as the Urgent scenario takes precedence but cannot be set via this parameter.            | No        |
 | `Visual`         | Microsoft.Toolkit.Uwp.Notifications.ToastVisual  | **Required.** ToastVisual object, created by `New-BTVisual`, representing the core content of the toast.   | Yes       |
 | `ToastPeople`    | Microsoft.Toolkit.Uwp.Notifications.ToastPeople  | ToastPeople object, representing recipient/persons (optional, used for group chat/etc).             | No        |
 | `CustomTimestamp`| DateTime                                        | Optional timestamp for when the toast is considered created (affects Action Center sort order).      | No        |

Help/New-BurntToastNotification.md

@@ -8,6 +8,7 @@ Creates and displays a rich Toast Notification for Windows.
 
 The `New-BurntToastNotification` function creates and displays a Toast Notification supporting text, images, sounds, progress bars, actions, snooze/dismiss, and more on Microsoft Windows 10+.
 Parameter sets ensure mutual exclusivity (e.g., you cannot use Silent and Sound together).
+The `-Urgent` switch will designate the toast as an "Important Notification" that can break through Focus Assist.
 
 ## PARAMETERS
 
@@ -32,6 +33,7 @@ Parameter sets ensure mutual exclusivity (e.g., you cannot use Silent and Sound
 | `ActivatedAction`  | ScriptBlock         | Script block to invoke when the toast is activated (clicked).                                               | No                                                         |
 | `DismissedAction`  | ScriptBlock         | Script block to invoke when the toast is dismissed by the user.                                             | No                                                         |
 | `EventDataVariable`| String              | The name of the global variable that will contain event data for use in event handler script blocks.        | No                                                         |
+| `Urgent`           | Switch              | Designates the toast as an "Important Notification" (scenario 'urgent'), allowing breakthrough of Focus Assist. | No |
 
 ## INPUTS
 
@@ -85,6 +87,14 @@ New-BurntToastNotification -Text 'Integration Complete' -Attribution 'Powered by
 
 Displays a notification with attribution at the bottom, e.g., "Powered by BurntToast".
 
+### Example: Important Notification with Urgent
+
+```powershell
+New-BurntToastNotification -Text 'Critical System Alert' -Urgent
+```
+
+Marks the notification as "Important", causing it to break through Focus Assist.
+
 ## LINKS
 
 - [New-BTButton](New-BTButton.md)

Help/Submit-BTNotification.md

@@ -7,7 +7,7 @@ Submits a completed toast notification for display.
 ## DESCRIPTION
 
 The `Submit-BTNotification` function submits a completed toast notification to the operating system's notification manager for display.
-This function supports advanced scenarios such as event callbacks for user actions or toast dismissal, sequence numbering to ensure correct update order, unique identification for toast replacement, expiration control, and direct Action Center delivery.
+This function supports advanced scenarios such as event callbacks for user actions or toast dismissal, sequence numbering to ensure correct update order, unique identification for toast replacement, expiration control, direct Action Center delivery, and designating a notification as "Important" (using the `-Urgent` switch) so that it can break through Focus Assist.
 
 When a script block is supplied for any of the event actions (`ActivatedAction`, `DismissedAction`, or `FailedAction`), the function ensures that only one registration for a logically identical handler is allowed per notification event type. This is accomplished by normalizing and hashing the script block; the resulting hash uniquely identifies the action for event registration purposes. Attempting to register the same handler multiple times for a given event will not create a duplicate subscription, but instead will produce an informative warning.
 
@@ -27,6 +27,7 @@ Specifying `-EventDataVariable` implicitly enables the behavior of `-ReturnEvent
 | `DataBinding`      | Hashtable   | Hashtable mapping strings to binding keys in a toast notification. Enables advanced updating scenarios.                | No        |
 | `ExpirationTime`   | DateTime    | When the notification is no longer relevant and should be removed from the Action Center.                             | No        |
 | `SuppressPopup`    | Switch      | If set, the notification is delivered directly to the Action Center (bypassing immediate display).                    | No        |
+| `Urgent`           | Switch      | If set, designates the toast as an "Important Notification" (scenario 'urgent') which can break through Focus Assist, ensuring the notification is delivered even when user focus mode is enabled. | No        |
 | `ActivatedAction`  | ScriptBlock | A script block executed if the user activates/clicks the toast notification.                                         | No        |
 | `DismissedAction`  | ScriptBlock | A script block executed if the user dismisses the toast notification.                                                | No        |
 | `FailedAction`     | ScriptBlock | A script block executed if the notification fails to display properly.                                               | No        |

Tests/New-BurntToastNotification.Tests.ps1

@@ -182,3 +182,9 @@ Context 'include attribution string' {
         $Log | Should -Be $Expected
     }
 }
+
+Context 'Urgent scenarios' {
+    It 'does not throw when using -Urgent' {
+        { New-BurntToastNotification -Text 'Critical Alert' -Urgent -WhatIf } | Should -Not -Throw
+    }
+}

Tests/Submit-BTNotification.Tests.ps1

@@ -47,4 +47,10 @@ Describe 'Submit-BTNotification' {
             $output | Should -Not -Contain "Duplicate or conflicting OnActivated ScriptBlock event detected"
         }
     }
+Context 'Urgent scenario' {
+    It 'runs without error with -Urgent' {
+        $mockContent = [Activator]::CreateInstance([Microsoft.Toolkit.Uwp.Notifications.ToastContent])
+        { Submit-BTNotification -Content $mockContent -Urgent -WhatIf } | Should -Not -Throw
+    }
+}
 }

src/Public/New-BTContent.ps1

@@ -26,6 +26,7 @@
 
         .PARAMETER Scenario
         Enum. Tells Windows to treat the toast as an alarm, reminder, or more (ToastScenario).
+        Will be ignored if toast is submitted with `-Urgent` switch on the Submit-BTNotification function, as the Urgent scenario takes precedence but cannot be set via this parameter.
 
         .PARAMETER Visual
         Required. ToastVisual object, created by New-BTVisual, representing the core content of the toast.

src/Public/New-BurntToastNotification.ps1

@@ -6,6 +6,7 @@
         .DESCRIPTION
         The New-BurntToastNotification function creates and displays a Toast Notification supporting text, images, sounds, progress bars, actions, snooze/dismiss, attribution, and more on Microsoft Windows 10+.
         Parameter sets ensure mutual exclusivity (e.g., you cannot use Silent and Sound together).
+        The `-Urgent` switch will designate the toast as an "Important Notification" that can break through Focus Assist.
 
         .PARAMETER Text
         Up to 3 strings to show within the Toast Notification. The first is the title.
@@ -64,6 +65,9 @@
         .PARAMETER EventDataVariable
         The name of the global variable that will contain event data for use in event handler script blocks.
 
+        .PARAMETER Urgent
+        If set, designates the toast as an "Important Notification" (scenario 'urgent'), allowing it to break through Focus Assist.
+
         .INPUTS
         None. You cannot pipe input to this function.
 
@@ -186,7 +190,9 @@
 
         [scriptblock] $DismissedAction,
 
-        [string] $EventDataVariable
+        [string] $EventDataVariable,
+
+        [switch] $Urgent
     )
 
     $ChildObjects = @()
@@ -300,6 +306,10 @@
         $ToastSplat.Add('EventDataVariable', $EventDataVariable)
     }
 
+    if ($Urgent) {
+        $ToastSplat.Add('Urgent', $true)
+    }
+
     if ($PSCmdlet.ShouldProcess( "submitting: $($Content.GetContent())" )) {
         Submit-BTNotification @ToastSplat
     }

src/Public/Submit-BTNotification.ps1

@@ -48,6 +48,9 @@
         .PARAMETER EventDataVariable
         If specified, assigns the $Event variable from notification callbacks to this global variable name (e.g., -EventDataVariable MyVar gives $global:MyVar in handlers). Implies ReturnEventData.
 
+        .PARAMETER Urgent
+        If set, designates the toast as an "Important Notification" (scenario 'urgent') which can break through Focus Assist, ensuring the notification is delivered even when user focus mode is enabled.
+
         .INPUTS
         None. You cannot pipe input to this function.
 
@@ -71,6 +74,7 @@
         [hashtable] $DataBinding,
         [datetime] $ExpirationTime,
         [switch] $SuppressPopup,
+        [switch] $Urgent,
         [scriptblock] $ActivatedAction,
         [scriptblock] $DismissedAction,
         [scriptblock] $FailedAction,
@@ -84,17 +88,29 @@
 
     $ToastXml = [Windows.Data.Xml.Dom.XmlDocument]::new()
 
+    $ToastXmlContent = $Content.GetContent()
+
     if (-not $DataBinding) {
-        $CleanContent = $Content.GetContent() -Replace '<text(.*?)>{', '<text$1>'
-        $CleanContent = $CleanContent.Replace('}</text>', '</text>')
-        $CleanContent = $CleanContent.Replace('="{', '="')
-        $CleanContent = $CleanContent.Replace('}" ', '" ')
-
-        $ToastXml.LoadXml($CleanContent)
-    } else {
-        $ToastXml.LoadXml($Content.GetContent())
+        $ToastXmlContent = $ToastXmlContent -replace '<text(.*?)>{', '<text$1>'
+        $ToastXmlContent = $ToastXmlContent.Replace('}</text>', '</text>')
+        $ToastXmlContent = $ToastXmlContent.Replace('="{', '="')
+        $ToastXmlContent = $ToastXmlContent.Replace('}" ', '" ')
     }
 
+    $ToastXml.LoadXml($ToastXmlContent)
+
+    # I've been unable to redirect the error from adjusting attributes on the Toast XML
+    # to just direct it to null, and so I'm temporarily changing the Error Action
+    # Preference and then changing it back to what it was originally.
+    $PrevErrorActionPref = $ErrorActionPreference
+    $ErrorActionPreference = 'SilentlyContinue'
+
+    if ($Urgent) {
+        $ToastXml.GetElementsByTagName('toast')[0].SetAttribute('scenario', 'urgent')
+    }
+
+    $ErrorActionPreference = $PrevErrorActionPref
+
     $Toast = [Windows.UI.Notifications.ToastNotification]::new($ToastXml)
 
     if ($DataBinding) {