gsadmin/WindowsNotifications
1
0
Fork 0
mirror of https://github.com/freedbygrace/WindowsNotifications.git synced 2026-08-08 10:13:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add PowerShell cmdlets and update project structure

Browse Source
This commit is contained in:
GraceSolutions
2025-04-10 21:13:24 -04:00
parent e5a7f10ade
commit 7cd5962115
56 changed files with 2356 additions and 3914 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+18 -259
View File
@@ -1,20 +1,26 @@
# Windows Notifications
A .NET DLL library for PowerShell 5 that displays notifications in user context from SYSTEM, with customization options, deferral support, LiteDB integration, and both synchronous/asynchronous operation modes.
A .NET DLL library for PowerShell 5 or 7 that displays notifications in user context from SYSTEM, with customization options, deferral support, LiteDB integration, and both synchronous/asynchronous operation modes.
## Features
- **User Context Notifications**: Display notifications in the user context from SYSTEM using user impersonation
- **Interactive Session Detection**: Only show notifications when an interactive user session (console or RDP) is present
- **Customizable Notifications**: Create simple or complex notifications with various customization options
- **Custom Branding**: Support for custom branding with logos, images, colors, and themes
- **Custom Branding**: Support for custom branding with logos, images, and attribution
- **Deferral Support**: Allow users to defer notifications (e.g., for system reboots)
- **State Persistence**: Save notification state using embedded LiteDB
- **PowerShell Integration**: Easily load and use the library in PowerShell 5
- **PowerShell Integration**: Easily load and use the library in PowerShell 5 or 7
- **Synchronous/Asynchronous Modes**: Run notifications in blocking or non-blocking mode
- **Countdown Display**: Show countdown timers for time-sensitive notifications
- **Deadline Actions**: Configure custom actions to execute when notification deadlines are reached
- **Logging**: Comprehensive logging of notification events and user interactions
## Project Structure
- `WindowsNotifications/` - Core .NET library
- `WindowsNotifications.Tests/` - Unit tests
- `PowerShell/` - PowerShell module
- `Examples/` - Example scripts
## Requirements
@@ -83,257 +89,14 @@ if ($result.ClickedButtonId) {
}
```
#### Reboot Notification with Deferrals
### PowerShell Module
The library includes a PowerShell module that makes it easier to use the Windows Notifications functionality in your PowerShell scripts.
```powershell
# Create a notification manager
$notificationManager = New-Object WindowsNotifications.NotificationManager
# Import the module
Import-Module WindowsNotifications
# Show a reboot notification
$result = $notificationManager.ShowRebootNotification(
"System Reboot Required",
"Your system needs to be rebooted to complete updates."
)
# Check the result
if ($result.ClickedButtonId -eq "reboot") {
# Reboot the system
Restart-Computer -Force
}
elseif ($result.Deferred) {
Write-Host "Reboot deferred until: $($result.DeferredUntil)"
}
```
### Advanced Usage
#### Custom Notification Options
```powershell
# Create a notification manager
$notificationManager = New-Object WindowsNotifications.NotificationManager
# Create custom notification options
$options = New-Object WindowsNotifications.Models.NotificationOptions
$options.Title = "Custom Notification"
$options.Message = "This is a custom notification"
$options.TimeoutInSeconds = 30
$options.Async = $true
$options.PersistState = $true
# Add buttons
$button1 = New-Object WindowsNotifications.Models.NotificationButton("OK", "ok")
$button2 = New-Object WindowsNotifications.Models.NotificationButton("Cancel", "cancel")
$options.Buttons.Add($button1)
$options.Buttons.Add($button2)
# Show the notification
$result = $notificationManager.ShowNotification($options)
```
#### Asynchronous Notifications
```powershell
# Create a notification manager
$notificationManager = New-Object WindowsNotifications.NotificationManager
# Create notification options with async mode
$options = New-Object WindowsNotifications.Models.NotificationOptions
$options.Title = "Background Task"
$options.Message = "A background task is running"
$options.Async = $true
# Show the notification
$result = $notificationManager.ShowNotification($options)
# Do some work
# ...
# Check if the notification has been interacted with
$currentResult = $notificationManager.GetNotificationResult($result.NotificationId)
if ($currentResult.Activated) {
Write-Host "User clicked the notification"
}
```
#### Custom Database Location
```powershell
# Create a notification manager with a custom database path
$dbPath = "C:\CustomPath\Notifications.db"
$notificationManager = New-Object WindowsNotifications.NotificationManager($dbPath)
# Show a notification
$result = $notificationManager.ShowSimpleNotification("Title", "Message")
```
#### Custom Branded Notifications
```powershell
# Create a notification manager
$notificationManager = New-Object WindowsNotifications.NotificationManager
# Create custom notification options with branding
$options = New-Object WindowsNotifications.Models.NotificationOptions
$options.Title = "IT Department Notification"
$options.Message = "Your system has been selected for a security update."
# Set branding properties
$options.BrandingText = "Contoso IT Department"
$options.BrandingColor = "#0078D7" # Blue
$options.AccentColor = "#E81123" # Red
$options.UseDarkTheme = $true
# Set custom images (file paths or URLs)
$options.LogoImagePath = "C:\Path\To\Logo.png" # Or "https://example.com/logo.png"
$options.HeroImagePath = "C:\Path\To\Banner.png"
$options.AppIconPath = "C:\Path\To\Icon.png"
# Add custom buttons with styling
$updateButton = New-Object WindowsNotifications.Models.NotificationButton("Install Update", "install")
$updateButton.BackgroundColor = "#107C10" # Green
$updateButton.TextColor = "#FFFFFF" # White
$options.Buttons.Add($updateButton)
# Show the notification
$result = $notificationManager.ShowNotification($options)
```
#### Countdown and Deadline Notifications
```powershell
# Create a notification manager
$notificationManager = New-Object WindowsNotifications.NotificationManager
# Create custom notification options
$options = New-Object WindowsNotifications.Models.NotificationOptions
$options.Title = "System Maintenance Required"
$options.Message = "Your system needs to restart for maintenance. Please save your work."
# Set deadline (5 minutes from now)
$options.DeadlineTime = (Get-Date).AddMinutes(5)
$options.ShowCountdown = $true
# Create deadline action (restart computer)
$deadlineAction = [WindowsNotifications.Models.DeadlineAction]::ExecuteScript(
"Write-Host 'System would restart now'; Start-Sleep -Seconds 5"
)
$options.DeadlineAction = $deadlineAction
# Enable logging
$options.EnableLogging = $true
$options.LogAction = {
param($logEntry)
Add-Content -Path "C:\Logs\notifications.log" -Value $logEntry
Write-Host $logEntry
}
# Show the notification
$result = $notificationManager.ShowNotification($options)
```
## API Reference
### NotificationManager Class
The main entry point for the Windows Notifications library.
#### Constructors
- `NotificationManager()` - Creates a new NotificationManager with the default database path
- `NotificationManager(string databasePath)` - Creates a new NotificationManager with the specified database path
#### Methods
- `NotificationResult ShowNotification(NotificationOptions options)` - Shows a notification with the specified options
- `NotificationResult ShowSimpleNotification(string title, string message)` - Shows a simple notification with the specified title and message
- `NotificationResult ShowNotificationWithButtons(string title, string message, params string[] buttons)` - Shows a notification with buttons
- `NotificationResult ShowRebootNotification(string title, string message, string rebootButtonText = "Reboot Now", string deferButtonText = "Defer")` - Shows a reboot notification with deferral options
- `NotificationResult GetNotificationResult(string notificationId)` - Gets the result of a notification
- `NotificationResult WaitForNotification(string notificationId, int timeout = -1)` - Waits for a notification to complete
- `List<NotificationResult> GetAllNotificationResults()` - Gets all notification results from the database
- `bool DeleteNotificationResult(string notificationId)` - Deletes a notification result from the database
- `bool DeleteAllNotificationResults()` - Deletes all notification results from the database
- `string GetDatabaseFilePath()` - Gets the path to the database file
- `bool IsRunningAsSystem()` - Checks if the current process is running as SYSTEM
- `List<string> GetInteractiveUserSessions()` - Gets all interactive user sessions
### NotificationOptions Class
Options for configuring a notification.
#### Properties
- `string Title` - The title of the notification
- `string Message` - The main message body of the notification
- `string LogoImagePath` - Optional logo image path
- `string HeroImagePath` - Optional hero image path
- `string Attribution` - Optional attribution text
- `int TimeoutInSeconds` - Optional timeout in seconds (0 = no timeout)
- `List<NotificationButton> Buttons` - Optional list of buttons to display
- `bool Async` - Whether to run the notification asynchronously
- `string Id` - Optional unique identifier for the notification
- `string Tag` - Optional tag for grouping notifications
- `string Group` - Optional group name for grouping notifications
- `DeferralOptions DeferralOptions` - Optional deferral options
- `bool ShowReminder` - Whether to show a reminder if the notification is not interacted with
- `int ReminderTimeInMinutes` - Time in minutes after which to show a reminder
- `bool PersistState` - Whether to persist the notification state in the database
- `bool EnableLogging` - Whether to enable logging for this notification
- `Action<string> LogAction` - Optional action to handle logging
- `Action<NotificationResult> OnActivated` - Optional action to execute when the notification is activated
- `Action<NotificationResult> OnTimeout` - Optional action to execute when the notification times out
- `Action<NotificationResult> OnError` - Optional action to execute when an error occurs
- `DateTime? DeadlineTime` - Optional deadline time for the notification
- `DeadlineAction DeadlineAction` - The action to take when the deadline is reached
- `bool ShowCountdown` - Whether to show a countdown timer on the notification
### NotificationResult Class
Represents the result of a notification interaction.
#### Properties
- `string NotificationId` - The unique identifier of the notification
- `bool Displayed` - Whether the notification was successfully displayed
- `bool Activated` - Whether the notification was activated (clicked)
- `bool Dismissed` - Whether the notification was dismissed
- `string ClickedButtonId` - The ID of the button that was clicked, if any
- `string ClickedButtonText` - The text of the button that was clicked, if any
- `string ClickedButtonArgument` - The argument of the button that was clicked, if any
- `DateTime CreatedTime` - The time when the notification was created
- `DateTime? InteractionTime` - The time when the notification was interacted with, if any
- `string ErrorMessage` - Any error message that occurred during the notification process
- `string ErrorCode` - The error code, if an error occurred
- `bool Deferred` - Whether the notification was deferred
- `DateTime? DeferredUntil` - The time when the notification was deferred until, if applicable
- `string DeferralReason` - The reason for deferral, if applicable
- `string DismissalReason` - The reason for dismissal, if applicable
- `string SystemAction` - The system action that was taken (e.g., snooze, dismiss)
- `bool DeadlineReached` - Whether the deadline was reached
- `DateTime? DeadlineReachedTime` - The time when the deadline was reached, if applicable
- `string DeadlineAction` - The action that was taken when the deadline was reached, if applicable
## PowerShell Module
The library includes a PowerShell module that makes it easier to use the Windows Notifications functionality in your PowerShell scripts. The module provides cmdlets for showing notifications, checking results, and managing notification history.
### Installing the PowerShell Module
1. Copy the files from the `PowerShell` directory 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:
```powershell
Import-Module WindowsNotifications
```
### Using the PowerShell Module
```powershell
# Initialize the module
Initialize-WindowsNotifications
@@ -342,9 +105,6 @@ Show-Notification -Title "Hello" -Message "This is a simple notification"
# Show a notification with buttons
$result = Show-Notification -Title "Action Required" -Message "Please select an option:" -Buttons "Approve", "Reject", "Defer"
# Show a reboot notification
$result = Show-Notification -Title "System Reboot Required" -Message "Your system needs to be rebooted." -RebootButtonText "Reboot Now" -DeferButtonText "Defer"
```
See the [PowerShell/README.md](PowerShell/README.md) file for more information about the PowerShell module.
@@ -365,10 +125,9 @@ See the [Examples](Examples) directory for complete PowerShell script examples:
## Building from Source
1. Clone the repository
2. Open the solution in Visual Studio
3. Restore NuGet packages
4. Build the solution in Release mode
5. The compiled DLL will be in the `WindowsNotifications\bin\Release` directory
2. Run the build script: `./build.ps1 -Release`
3. The compiled DLL will be in the `WindowsNotifications\bin\Release` directory
4. The PowerShell module will be in the `PowerShell` directory
## License