Custom Powershell Notification Script Using BurntToast Module

You are currently viewing Custom Powershell Notification Script Using BurntToast Module

Custom Powershell Notification Script Using BurntToast Module

As a Windows administrator, communication with users or even with yourself can be a challenge when you’re dealing with critical system updates, reminders, or maintenance schedules. BurntToast, a PowerShell module, simplifies the process by enabling you to create visually appealing and interactive toast notifications on Windows systems.

Imagine being able to:

  • Alert users to restart their machines after a software update.
  • Notify teams about upcoming downtime.
  • Provide yourself with custom reminders or alerts during your workflows.

These notifications can be customized with text, buttons, and images, and they are ideal for both individual use and organization-wide deployment. For administrators, this script can be deployed using Group Policy Objects (GPO) and / or automated through a scheduled task, ensuring notifications are timely and consistent.

Overview of the Powershell Script

This script:

  • Allows customization of text, buttons, and images for notifications.
  • Supports multilingual notifications based on the system’s locale.
  • Uses parameter sets to enable flexible inputs for different scenarios, such as restart reminders or custom messages.

We’ll go through the script step by step to understand its functionality.

Step 1: Declaring Parameters

The script begins by defining its input parameters using the param block.

param(
    [ValidateNotNullOrEmpty()]
    [String]$AppId = "windows.immersivecontrolpanel_cw5n1h2txyewy!microsoft.windows.immersivecontrolpanel",
    
    [Parameter(Mandatory=$true, ParameterSetName = "Restart")]
    [switch]$Restart,
    
    [ValidateNotNullOrEmpty()]
    [string]$HeroImageSource = "C:\\Path\\To\\HeroImage.png",
    
    [ValidateNotNullOrEmpty()]
    [string]$AppLogoSource = "C:\\Path\\To\\AppLogo.png",
    
    [ValidateNotNullOrEmpty()]
    [Parameter(Mandatory=$true,ParameterSetName = "CustomMessage")]    
    [string]$TextMessage,
    
    [ValidateNotNullOrEmpty()]
    [Parameter(Mandatory=$true,ParameterSetName = "CustomMessage")]    
    [string]$ButtonText,
    
    [ValidateNotNullOrEmpty()]
    [Parameter(Mandatory=$true,ParameterSetName = "CustomMessage")]
    [string]$NotificationHeader
)

What’s Happening Here?

  • The script uses parameters to control its behavior. For example:
    • $AppId: Identifies the app associated with the notification.
    • $Restart: A switch that determines if the script should display a restart reminder.
    • $HeroImageSource and $AppLogoSource: Paths to images for customizing the notification’s appearance.
    • $TextMessage, $ButtonText, $NotificationHeader: Parameters for specifying the text and layout of a custom message.

By using parameter sets (ParameterSetName), the script enforces which parameters are required depending on whether it’s showing a restart notification or a custom message.

Step 2: Locale Detection

$windowsLocale = Get-WinSystemLocale

This ensures that notifications are shown in the user’s language. For example, if the system locale is de-DE (German), the script can display messages in German.

Step 3: Handling Restart Notifications

if($Restart){
    switch($windowsLocale){
        "es-MX" {
            $TextMessage = "Por favor reinicie su computadora."
            $ButtonText = "¡Recuérdamelo en 10 minutos!"
            $NotificationHeader = "Reinicio requerido"
        }
        "de-DE" {
            $TextMessage = "Bitte starte deinen PC neu, damit die neuesten Änderungen übernommen werden können."
            $ButtonText = "Erinnere mich in 10 Minuten!"
            $NotificationHeader = "Neustart erforderlich"
        }
        default {
            $TextMessage = "Please restart your Computer to apply the latest Changes."
            $ButtonText = "Remind me in 10 Minutes!"
            $NotificationHeader = "Restart required"
        }
    }
}

How It Works:

  • A switch statement evaluates $windowsLocale to match specific locales (e.g., es-MX for Spanish-Mexico).
  • Based on the match, the script sets localized values for $TextMessage, $ButtonText, and $NotificationHeader.

If the locale doesn’t match predefined values, it defaults to English.

Step 4: Generating Toast Notification Content

heroImage = New-BTImage -Source $HeroImageSource -HeroImage
$logo = New-BTImage -Source $AppLogoSource -AppLogoOverride -Crop None

These lines load the specified images and define their roles in the notification:

  • $heroImage: A prominent image at the top of the notification.
  • $logo: An optional logo displayed next to the message.
$header = New-BTHeader -Title $NotificationHeader -Id "ToastHeader"
$text = New-BTText -Text $TextMessage
  • $header: Sets the notification’s title.
  • $text: Defines the message content.
$snoozeButton = New-BTButton -Content $ButtonText -Snooze
$action = New-BTAction -Buttons $snoozeButton
  • $snoozeButton: Creates a button with a snooze action, allowing users to defer the reminder.
  • $action: Groups the button into an actionable element for the notification.
$binding = New-BTBinding -Children $text -HeroImage $heroImage -AppLogoOverride $logo
$visiual = New-BTVisual -BindingGeneric $binding
$content = New-BTContent -Visual $visiual -Scenario Reminder -Actions $action -Header $header

This combines all the components—images, text, buttons—into a complete notification structure.

Submit-BTNotification -Content $content -AppId $AppId
Full Script
PowerShell
param(
    [ValidateNotNullOrEmpty()]
    [String]$AppId = "windows.immersivecontrolpanel_cw5n1h2txyewy!microsoft.windows.immersivecontrolpanel",
    [Parameter(Mandatory=$true,
    ParameterSetName = "Restart")]
    [switch]$Restart,

    [ValidateNotNullOrEmpty()]
    [string]$HeroImageSource = "C:\Users\0x54696D\Downloads\logo.png",
    [ValidateNotNullOrEmpty()]
    [string]$AppLogoSource = "C:\Users\0x54696D\Downloads\ps_logo.png",

    [ValidateNotNullOrEmpty()]
    [Parameter(Mandatory=$true,ParameterSetName = "CustomMessage")]
    [string]$TextMessage,
    [ValidateNotNullOrEmpty()]
    [Parameter(Mandatory=$true,ParameterSetName = "CustomMessage")]
    [string]$ButtonText,
    [ValidateNotNullOrEmpty()]
    [Parameter(Mandatory=$true,ParameterSetName = "CustomMessage")]
    [string]$NotificationHeader
    
)
$windowsLocale = Get-WinSystemLocale

if($Restart){
    switch($windowsLocale){
    "es-MX" {
        $TextMessage = "Por favor reinicie su computadora."
        $ButtonText = "¡Recuérdamelo en 10 minutos!"
        $NotificationHeader = "Reinicio requerido"
    }
    "de-DE" {
        $TextMessage = "Bitte starte deinen PC neu, damit die neuesten Änderungen übernommen werden können."
        $ButtonText = "Erinnere mich in 10 Minuten!"
        $NotificationHeader = "Neustart erforderlich"
    }
    default {
        $TextMessage = "Please restart your Computer to apply the latest Changes."
        $ButtonText = "Remind me in 10 Minutes!"
        $NotificationHeader = "Restart required"
                    
    }

 }
}

Import-Module BurntToast 
$heroImage = New-BTImage -Source $HeroImageSource -HeroImage
$logo = New-BTImage -Source $AppLogoSource -AppLogoOverride -Crop None    
$header = New-BTHeader -Title $NotificationHeader -Id "ToastHeader"
$text = New-BTText -Text $TextMessage
$snoozeButton = New-BTButton -Content $ButtonText -Snooze
$action = New-BTAction -Buttons $snoozeButton
$binding = New-BTBinding -Children $text -HeroImage $heroImage -AppLogoOverride $logo
$visiual = New-BTVisual -BindingGeneric $binding 
$content = New-BTContent -Visual $visiual -Scenario Reminder -Actions $action -Header $header
Submit-BTNotification -Content $content -AppId $AppId

Leave a Reply