mirror of
https://github.com/freedbygrace/WindowsNotifications.git
synced 2026-07-26 12:08:14 +00:00
Update PowerShell module to use Write-Output instead of Write-Host and load assembly through PSD1
This commit is contained in:
GraceSolutions
+54
-151
@@ -1,6 +1,6 @@
|
||||
# WindowsNotifications PowerShell Module
|
||||
# Windows Notifications PowerShell Module
|
||||
|
||||
This PowerShell module provides a convenient way to use the Windows Notifications library from PowerShell scripts.
|
||||
This PowerShell module provides a simple interface to the Windows Notifications library, allowing you to display notifications in user context from SYSTEM.
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -17,22 +17,17 @@ This PowerShell module provides a convenient way to use the Windows Notification
|
||||
|
||||
## Usage
|
||||
|
||||
### Initialize the Module
|
||||
|
||||
Before using the module, you need to initialize it:
|
||||
### Initializing the Module
|
||||
|
||||
```powershell
|
||||
# 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 with custom database path
|
||||
Initialize-WindowsNotifications -DatabasePath "C:\Path\To\Notifications.db"
|
||||
```
|
||||
|
||||
### Show Notifications
|
||||
### Showing Notifications
|
||||
|
||||
#### Simple Notification
|
||||
|
||||
@@ -45,50 +40,71 @@ Show-Notification -Title "Hello" -Message "This is a simple notification"
|
||||
```powershell
|
||||
$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"
|
||||
# Check which button was clicked
|
||||
if ($result.ClickedButtonId) {
|
||||
Write-Host "Button clicked: $($result.ClickedButtonText)"
|
||||
}
|
||||
```
|
||||
|
||||
#### Reboot Notification with Deferrals
|
||||
#### Reboot Notification
|
||||
|
||||
```powershell
|
||||
$result = Show-Notification -Title "System Reboot Required" -Message "Your system needs to be rebooted." -RebootButtonText "Reboot Now" -DeferButtonText "Defer"
|
||||
|
||||
# Check if the reboot button was clicked
|
||||
if ($result.ClickedButtonId -eq "reboot") {
|
||||
# Reboot the system
|
||||
Restart-Computer -Force
|
||||
}
|
||||
```
|
||||
|
||||
#### Advanced Options
|
||||
#### Asynchronous Notification
|
||||
|
||||
```powershell
|
||||
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
|
||||
$result = Show-Notification -Title "Background Task" -Message "A background task is running..." -Async
|
||||
|
||||
# Do some work
|
||||
# ...
|
||||
|
||||
# Check if the notification has been interacted with
|
||||
$currentResult = Get-NotificationResult -NotificationId $result.NotificationId
|
||||
if ($currentResult.Activated) {
|
||||
Write-Host "User clicked the notification"
|
||||
}
|
||||
```
|
||||
|
||||
### Work with Notification Results
|
||||
#### Notification with Deadline
|
||||
|
||||
```powershell
|
||||
# Get the result of a notification
|
||||
$result = Get-NotificationResult -NotificationId "notification-id"
|
||||
$deadline = (Get-Date).AddMinutes(5)
|
||||
$result = Show-Notification -Title "System Maintenance" -Message "Your system needs maintenance." -DeadlineTime $deadline -ShowCountdown
|
||||
|
||||
# Check if the deadline was reached
|
||||
if ($result.DeadlineReached) {
|
||||
Write-Host "Deadline reached at $($result.DeadlineReachedTime)"
|
||||
}
|
||||
```
|
||||
|
||||
### Managing Notification Results
|
||||
|
||||
```powershell
|
||||
# Get a specific notification result
|
||||
$result = Get-NotificationResult -NotificationId "12345678-1234-1234-1234-123456789012"
|
||||
|
||||
# Wait for a notification to complete
|
||||
$result = Wait-Notification -NotificationId "notification-id" -TimeoutInSeconds 30
|
||||
$result = Wait-Notification -NotificationId "12345678-1234-1234-1234-123456789012" -TimeoutInSeconds 30
|
||||
|
||||
# Get all notification history
|
||||
$history = Get-NotificationHistory
|
||||
# Get all notification results
|
||||
$results = Get-AllNotificationResults
|
||||
|
||||
# Remove notification history
|
||||
Remove-NotificationHistory -NotificationId "notification-id"
|
||||
# Remove a notification result
|
||||
Remove-NotificationResult -NotificationId "12345678-1234-1234-1234-123456789012"
|
||||
|
||||
# Remove all notification history
|
||||
Remove-NotificationHistory
|
||||
# Clear all notification results
|
||||
Clear-AllNotificationResults
|
||||
```
|
||||
|
||||
### System Information
|
||||
### Utility Functions
|
||||
|
||||
```powershell
|
||||
# Check if running as SYSTEM
|
||||
@@ -98,127 +114,14 @@ $isSystem = Test-SystemContext
|
||||
$sessions = Get-InteractiveUserSessions
|
||||
```
|
||||
|
||||
## Command Reference
|
||||
## Functions
|
||||
|
||||
| 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:
|
||||
|
||||
```powershell
|
||||
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
|
||||
|
||||
```powershell
|
||||
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
|
||||
|
||||
```powershell
|
||||
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
|
||||
|
||||
```powershell
|
||||
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
|
||||
|
||||
```powershell
|
||||
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)"
|
||||
```
|
||||
- `Initialize-WindowsNotifications` - Initializes the Windows Notifications module
|
||||
- `Show-Notification` - Shows a notification
|
||||
- `Get-NotificationResult` - Gets the result of a notification
|
||||
- `Wait-Notification` - Waits for a notification to complete
|
||||
- `Get-AllNotificationResults` - Gets all notification results
|
||||
- `Remove-NotificationResult` - Removes a notification result
|
||||
- `Clear-AllNotificationResults` - Clears all notification results
|
||||
- `Test-SystemContext` - Checks if running as SYSTEM
|
||||
- `Get-InteractiveUserSessions` - Gets interactive user sessions
|
||||
|
||||
Reference in New Issue
Block a user