WindowsNotifications/PowerShell/README.md

WindowsNotifications PowerShell Module

This PowerShell module provides a convenient way to use the Windows Notifications library from PowerShell scripts.

Installation

1. Copy the module files to one of the following locations:

   • %UserProfile%\Documents\WindowsPowerShell\Modules\WindowsNotifications (for the current user)
   • %ProgramFiles%\WindowsPowerShell\Modules\WindowsNotifications (for all users)

2. Make sure the WindowsNotifications.dll file is in the same directory as the module files.

3. Import the module:

   Import-Module WindowsNotifications
   

Usage

Initialize the Module

Before using the module, you need to initialize it:

# Initialize with default settings
Initialize-WindowsNotifications

# Or initialize with a custom assembly path
Initialize-WindowsNotifications -AssemblyPath "C:\Path\To\WindowsNotifications.dll"

# Or initialize with a custom database path
Initialize-WindowsNotifications -DatabasePath "C:\Path\To\Notifications.db"

Show Notifications

Simple Notification

Show-Notification -Title "Hello" -Message "This is a simple notification"

Notification with Buttons

$result = Show-Notification -Title "Action Required" -Message "Please select an option:" -Buttons "Approve", "Reject", "Defer"

if ($result.ClickedButtonText -eq "Approve") {
    Write-Host "User approved the action"
}

Reboot Notification with Deferrals

$result = Show-Notification -Title "System Reboot Required" -Message "Your system needs to be rebooted." -RebootButtonText "Reboot Now" -DeferButtonText "Defer"

if ($result.ClickedButtonId -eq "reboot") {
    # Reboot the system
    Restart-Computer -Force
}

Advanced Options

Show-Notification -Title "Advanced Notification" -Message "This notification has advanced options" `
    -Async -PersistState -TimeoutInSeconds 30 -LogoImagePath "C:\Path\To\Logo.png" `
    -HeroImagePath "C:\Path\To\Hero.png" -ShowReminder -ReminderTimeInMinutes 5

Work with Notification Results

# Get the result of a notification
$result = Get-NotificationResult -NotificationId "notification-id"

# Wait for a notification to complete
$result = Wait-Notification -NotificationId "notification-id" -TimeoutInSeconds 30

# Get all notification history
$history = Get-NotificationHistory

# Remove notification history
Remove-NotificationHistory -NotificationId "notification-id"

# Remove all notification history
Remove-NotificationHistory

System Information

# Check if running as SYSTEM
$isSystem = Test-SystemContext

# Get interactive user sessions
$sessions = Get-InteractiveUserSessions

Command Reference

Command	Description
Initialize-WindowsNotifications	Initializes the Windows Notifications module
Show-Notification	Shows a notification with various options
Get-NotificationResult	Gets the result of a notification
Wait-Notification	Waits for a notification to complete
Get-NotificationHistory	Gets all notification results from the database
Remove-NotificationHistory	Deletes notification results from the database
Get-InteractiveUserSessions	Gets all interactive user sessions
Test-SystemContext	Checks if the current process is running as SYSTEM

Custom Branding

The module supports custom branding for notifications, allowing you to create notifications that match your organization's branding:

Show-Notification -Title "IT Department Notification" -Message "System update required" `
    -BrandingText "Contoso IT" `
    -BrandingColor "#0078D7" `
    -AccentColor "#E81123" `
    -LogoImagePath "C:\Path\To\Logo.png" `
    -HeroImagePath "C:\Path\To\Banner.png" `
    -UseDarkTheme

Supported Branding Options

Option	Description
BrandingText	Custom branding text (e.g., company or department name)
BrandingColor	Custom branding color (hex format: #RRGGBB)
AccentColor	Custom accent color for the notification (hex format: #RRGGBB)
UseDarkTheme	Whether to use dark theme for the notification
LogoImagePath	Path or URL to a logo image
HeroImagePath	Path or URL to a hero/banner image
InlineImagePath	Path or URL to an inline image
AppIconPath	Path or URL to an app icon
BackgroundImagePath	Path or URL to a background image
AudioSource	Audio source for the notification
SilentMode	Whether to show the notification in silent mode (no sound)
DeadlineTime	Deadline time for the notification
ShowCountdown	Whether to show a countdown timer on the notification
DeadlineActionCommand	Command to execute when the deadline is reached
DeadlineActionArguments	Arguments for the deadline command
DeadlineActionUrl	URL to open when the deadline is reached
DeadlineActionScript	PowerShell script to execute when the deadline is reached
EnableLogging	Whether to enable logging for the notification
LogFilePath	Path to the log file

Examples

Example 1: Simple Notification

Import-Module WindowsNotifications
Initialize-WindowsNotifications

$result = Show-Notification -Title "Hello" -Message "This is a simple notification"
Write-Host "Notification displayed: $($result.Displayed)"

Example 2: Notification with Buttons

Import-Module WindowsNotifications
Initialize-WindowsNotifications

$result = Show-Notification -Title "Action Required" -Message "Please select an option:" -Buttons "Approve", "Reject", "Defer"

if ($result.ClickedButtonId) {
    Write-Host "Button clicked: $($result.ClickedButtonText)"

    switch ($result.ClickedButtonText) {
        "Approve" { Write-Host "User approved the action" }
        "Reject" { Write-Host "User rejected the action" }
        "Defer" { Write-Host "User deferred the action" }
    }
}

Example 3: Asynchronous Notification

Import-Module WindowsNotifications
Initialize-WindowsNotifications

$result = Show-Notification -Title "Background Task" -Message "A background task is running" -Async

# Do some work
for ($i = 1; $i -le 5; $i++) {
    Write-Host "Working... ($i/5)"
    Start-Sleep -Seconds 2

    # Check if the notification has been interacted with
    $currentResult = Get-NotificationResult -NotificationId $result.NotificationId

    if ($currentResult.Activated -or $currentResult.Dismissed) {
        Write-Host "User interacted with the notification"
        break
    }
}

Write-Host "Work completed"

Example 4: Countdown and Deadline Notification

Import-Module WindowsNotifications
Initialize-WindowsNotifications

# Create a notification with a deadline 5 minutes from now
$result = Show-Notification -Title "System Maintenance" -Message "Your system needs to restart soon." `
    -Buttons "Restart Now", "Defer" `
    -DeadlineTime (Get-Date).AddMinutes(5) `
    -ShowCountdown `
    -DeadlineActionScript "Restart-Computer -Force" `
    -EnableLogging `
    -LogFilePath "C:\Logs\notifications.log"

Write-Host "Notification displayed with deadline: $($result.Displayed)"