Toast Notifications

What This Script Does

The Send-ToastNotification.ps1 script is a helper function that provides a clean, reusable interface for displaying Windows 10 and Windows 11 toast notifications from PowerShell. Toast notifications are the modern notification pop-ups that appear in the lower-right corner of the Windows desktop (or in the notification center on newer builds), providing non-intrusive visual feedback to the user. This script is used internally by other scripts in the Chocolatey Scripts toolkit, particularly the auto-update script, to communicate results and status information without requiring the user to actively monitor a console window.

Unlike the other scripts in the toolkit that are designed to be run directly, Send-ToastNotification.ps1 is structured as a PowerShell function that is dot-sourced (imported) by other scripts. When another script in the toolkit needs to display a notification, it imports this function and calls it with the appropriate parameters. This design pattern avoids duplicating notification logic across multiple scripts and ensures consistent notification behavior throughout the toolkit. If you want to customize how notifications look or behave, you only need to modify this single file.

The function accepts four parameters that control the content and appearance of the notification. The Title parameter sets the bold heading text at the top of the notification, typically identifying which script or operation generated the notification. The Message parameter provides the body text with detailed information, such as the number of packages updated or a summary of errors encountered. The Type parameter controls the visual style of the notification, accepting values of Info, Success, Warning, or Error. Each type corresponds to a different visual treatment, helping users quickly distinguish between routine informational messages and notifications that require attention.

Under the hood, the function uses the Windows Runtime (WinRT) Windows.UI.Notifications API to create and display toast notifications. This is the same API that native Windows applications use for their notifications, which means the notifications generated by this function look and behave identically to notifications from any other Windows application. They appear in the notification center, respect the user's notification settings (including Do Not Disturb mode), and can be dismissed or interacted with in the standard way. The function loads the required WinRT assemblies at runtime, so there are no additional dependencies to install.

The notification XML template used by the function follows the standard Windows toast notification schema. This schema defines the structure of the notification content, including the text elements, optional images, and interactive elements. The current implementation uses a clean two-line text layout with the title on the first line and the message on the second, which provides good readability without being overly complex. The notification is configured with a standard duration (approximately 5 seconds of visibility before moving to the notification center), which balances visibility with non-intrusiveness.

One important technical consideration is that toast notifications require an application identity to be registered with the Windows notification system. The function uses the PowerShell application identity by default, which means notifications appear as coming from PowerShell in the notification center. This is appropriate for a scripting toolkit where PowerShell is the execution environment. The application identity also determines which icon appears alongside the notification, so users will see the PowerShell icon in their notification area when these notifications are displayed.

The Type parameter influences how the notification content is formatted to provide visual cues about the nature of the message. Success notifications typically indicate that an operation completed without issues, such as when all packages are successfully updated. Warning notifications indicate that an operation completed but with some issues that may need attention, such as when most packages updated successfully but one or two failed. Error notifications indicate a significant problem that prevented the operation from completing, such as a network failure that blocked all updates. Info notifications are used for neutral informational messages that do not indicate a problem.

Error handling in this function is deliberately silent. If a notification fails to display for any reason (such as the notification service being disabled, the system running a version of Windows that does not support WinRT notifications, or a permissions issue), the function catches the error and returns without throwing an exception. This is intentional because toast notifications are a supplementary feedback mechanism, not a critical operation. The parent scripts that call this function should not fail or alter their behavior just because a notification could not be displayed. The actual results of maintenance operations are always logged to files regardless of whether the notification succeeds.

The function is designed to work exclusively on Windows 10 and Windows 11. Earlier versions of Windows do not support the WinRT notification API, and attempting to use it on those systems would produce errors. The function includes a version check at the start that verifies the operating system supports toast notifications before attempting to create one. On unsupported systems, the function returns silently, allowing the parent scripts to run without modification on older Windows versions even though notifications will not be displayed.

For users who want to use this notification function in their own PowerShell scripts beyond the Chocolatey Scripts toolkit, the function can be imported independently. Simply dot-source the script file in your PowerShell session or script, and the Send-ToastNotification function becomes available for use. This makes it a versatile utility for any PowerShell automation project that would benefit from user-facing notifications, whether it involves Chocolatey or not. The function's simple parameter interface makes it straightforward to integrate into any workflow.

The notification system plays a particularly important role in the context of scheduled tasks. When the auto-update or cleanup scripts run via Task Scheduler in the background, there is no console window for the user to monitor. Without notifications, the user would have no way of knowing that maintenance ran or what the outcome was unless they proactively checked the log files. Toast notifications bridge this gap by providing immediate visual feedback when a user is logged in. If the user is not logged in when the scheduled task runs, the notification simply does not display, and the results remain available in the log files for later review.

Usage

The function is typically imported and called from other scripts rather than run directly.

# Import the function (dot-source)
. .\Send-ToastNotification.ps1

# Display an informational notification
Send-ToastNotification -Title "Chocolatey Update" `
    -Message "Checking for package updates..." `
    -Type Info

# Display a success notification
Send-ToastNotification -Title "Update Complete" `
    -Message "All 24 packages are up to date." `
    -Type Success

# Display a warning notification
Send-ToastNotification -Title "Update Completed with Warnings" `
    -Message "22 packages updated, 2 failed. Check logs for details." `
    -Type Warning

# Display an error notification
Send-ToastNotification -Title "Update Failed" `
    -Message "Network error prevented package updates. Will retry next run." `
    -Type Error

Parameters

Parameter	Type	Required	Description
-Title	String	Yes	The bold heading text displayed at the top of the notification.
-Message	String	Yes	The body text with detailed information about the event.
-Type	String	No	The notification style: Info, Success, Warning, or Error. Defaults to Info.

What Gets Changed

• Windows notifications — Displays a toast notification in the Windows notification center. No files or settings are modified.
• No persistent changes — This function is purely for display purposes and does not write to disk, modify settings, or alter system state.

Related Scripts