Public/Write-ssConsoleLog.ps1
|
function Write-ssConsoleLog { <# .SYNOPSIS Writes a formatted log message to the host with structured visual prefixes, colour styling, optional timestamp support, optional blank lines, and optional emoji symbols. .DESCRIPTION Write-ssConsoleLog provides a consistent, structured logging format for scripts and modules in enterprise and DevOps environments. It standardises console output by applying semantic message types, visual prefixes, indentation rules, and optional timestamping. The function is designed to improve readability, operational traceability, and phase separation within structured automation workflows. Message Types: Information [i] / ℹ️ Cyan or Gray General status updates Success [+] / ✅ Green A task completed successfully Warning [!] / ⚠️ Yellow Non-critical issue or action required Failure [x] / ❌ Red A step failed but execution may continue Critical [X] / 🛑 Red on White BG Terminating error — script is aborting Input [?] / ❓ Magenta Waiting for user input Detail > / ▸ Dark Gray Nested or secondary information Critical messages are intended to represent terminating conditions. Failure messages represent non-terminating errors. Detail messages are indented beneath primary log entries for hierarchy clarity. .PARAMETER Message The text message to display. This parameter is mandatory and represents the primary log content. .PARAMETER Type Specifies the message type and formatting style. Valid values: - Info - Success - Warn - Failure - Critical - Input - Detail Default value: 'Info' .PARAMETER Timestamp If specified, prepends the message with the current date and time in ISO format (yyyy-MM-dd HH:mm:ss). This improves traceability in deployment logs and operational diagnostics. .PARAMETER BlankLineBefore If specified, writes a blank line before the log message. Useful for: - Visually separating logical phases - Emphasising important events - Improving console readability in long-running scripts .PARAMETER BlankLineAfter If specified, writes a blank line after the log message. Useful for: - Isolating critical or success messages - Creating visual grouping boundaries - Improving structured layout in complex output streams .PARAMETER UseEmoji If specified, replaces the standard text symbols (e.g., [i], [X]) with corresponding emojis (e.g., ℹ️, 🛑). Intended primarily for interactive or modern terminal environments. For minimal or legacy environments, omit this switch. .EXAMPLE Write-ssConsoleLog "Connecting to Graph..." -UseEmoji Displays an informational message using the ℹ️ emoji. .EXAMPLE Write-ssConsoleLog "Deployment completed successfully." -Type Success -UseEmoji Displays a success message in green using the ✅ emoji. .EXAMPLE Write-ssConsoleLog "Unable to delete record." -Type Failure -UseEmoji Displays a non-terminating failure message using the ❌ emoji. .EXAMPLE Write-ssConsoleLog "Authentication failed. Aborting." -Type Critical -Timestamp -BlankLineBefore -BlankLineAfter -UseEmoji Displays a timestamped critical message using the 🛑 emoji, with red foreground, white background, and blank lines both before and after the message for visual isolation. .EXAMPLE Write-ssConsoleLog "Enter device name:" -Type Input -UseEmoji Displays a user input indicator message using the ❓ emoji. .EXAMPLE Write-ssConsoleLog "Checking connectivity..." -Type Info -UseEmoji Write-ssConsoleLog "Ping test failed." -Type Detail -UseEmoji Displays a primary informational message followed by an indented detail line, both using emojis. .OUTPUTS None. This function writes directly to the host using Write-Host and does not emit objects to the pipeline. .NOTES Author: owen.heaume Version: 1.1 - Added BlankLineAfter parameter Design Considerations: - Host-dependent output (Write-Host) - Structured semantic logging categories - Visual hierarchy via indentation - Backward-compatible parameter extension - Suitable for enterprise automation and DevOps scripting #> param( [Parameter(Mandatory, Position = 0)] [string]$Message, [ValidateSet('Info', 'Success', 'Warn', 'Failure', 'Critical', 'Input', 'Detail')] [string]$Type = 'Info', [switch]$Timestamp, [switch]$BlankLineBefore, [switch]$BlankLineAfter, [switch]$UseEmoji ) $Style = switch ($Type) { 'Info' { @{ Symbol = '[i]'; Color = 'Cyan'; Indent = 0; Emoji = 'ℹ️' } } 'Success' { @{ Symbol = '[+]'; Color = 'Green'; Indent = 0; Emoji = '✅' } } 'Warn' { @{ Symbol = '[!]'; Color = 'Yellow'; Indent = 0; Emoji = '⚠️' } } 'Failure' { @{ Symbol = '[x]'; Color = 'Red'; Indent = 0; Emoji = '❌' } } 'Critical' { @{ Symbol = '[X]'; Color = 'Red'; Background = 'White'; Indent = 0; Emoji = '🛑' } } 'Input' { @{ Symbol = '[?]'; Color = 'Magenta'; Indent = 0; Emoji = '❓' } } 'Detail' { @{ Symbol = '>'; Color = 'DarkGray'; Indent = 4; Emoji = '▸' } } } $indentSpaces = ' ' * $Style.Indent $timePrefix = if ($Timestamp) { '[{0}] ' -f (Get-Date -Format 'yyyy-MM-dd HH:mm:ss') } $displaySymbol = if ($UseEmoji) { $Style.Emoji } else { $Style.Symbol } $text = if ($Type -eq 'Detail') { "$indentSpaces$timePrefix$displaySymbol $Message" } else { "$timePrefix$displaySymbol $Message" } if ($BlankLineBefore) { Write-Host '' } if ($Type -eq 'Critical') { Write-Host $text -ForegroundColor $Style.Color -BackgroundColor $Style.Background } else { Write-Host $text -ForegroundColor $Style.Color } if ($BlankLineAfter) { Write-Host '' } } |