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
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