diff --git a/Docs/Readme.md b/Docs/Readme.md index 70bb00f..7576a33 100644 --- a/Docs/Readme.md +++ b/Docs/Readme.md @@ -2,7 +2,7 @@ Module Name: PSWriteColor Module Guid: 0b0ba5c5-ec85-4c2b-a718-874e55a8bc3f Download Help Link: https://github.com/EvotecIT/PSWriteColor -Help Version: 1.0.4 +Help Version: 1.0.5 Locale: en-US --- # PSWriteColor Module diff --git a/Docs/Write-Color.md b/Docs/Write-Color.md index cb84605..d9b0e69 100644 --- a/Docs/Write-Color.md +++ b/Docs/Write-Color.md @@ -11,7 +11,7 @@ Write-Color is a wrapper around Write-Host delivering a lot of additional featur ## SYNTAX ### __AllParameterSets ```powershell -Write-Color [[-Text] ] [[-Color] ] [[-BackGroundColor] ] [[-StartTab] ] [[-LinesBefore] ] [[-LinesAfter] ] [[-StartSpaces] ] [[-LogFile] ] [[-DateTimeFormat] ] [[-LogTime] ] [[-LogRetry] ] [[-Encoding] ] [[-PadLeft] ] [[-PadCenter] ] [[-PadRight] ] [[-PadCharacter] ] [-ShowTime] [-NoNewLine] [-HorizontalCenter] [-NoConsoleOutput] [] +Write-Color [[-Text] ] [[-Color] ] [[-BackGroundColor] ] [[-StartTab] ] [[-LinesBefore] ] [[-LinesAfter] ] [[-StartSpaces] ] [[-LogFile] ] [[-DateTimeFormat] ] [[-LogTime] ] [[-LogRetry] ] [[-Encoding] ] [[-PadLeft] ] [[-PadCenter] ] [[-PadRight] ] [[-PadCharacter] ] [[-OutputStream] ] [-ShowTime] [-NoNewLine] [-HorizontalCenter] [-NoConsoleOutput] [] ``` ## DESCRIPTION @@ -294,6 +294,27 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -OutputStream +Destination for messages: Host (default), Verbose, or Information. +Verbose and Information emit one joined text record per call and respect their +normal PowerShell preferences. Use -Verbose or -InformationAction Continue to display them. +ShowTime is supported; console colors, padding, indentation, blank lines, centering, +and NoNewLine apply only to Host. NoConsoleOutput suppresses any selected message +stream while retaining file logging. No messages are written to success output. + +```yaml +Type: String +Parameter Sets: __AllParameterSets +Aliases: None +Possible values: Host, Verbose, Information + +Required: False +Position: 16 +Default value: Host +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -PadCenter Minimum combined text width, with padding on both sides. An odd extra character goes on the right. diff --git a/PSWriteColor.psd1 b/PSWriteColor.psd1 index 9193811..dbb4214 100644 --- a/PSWriteColor.psd1 +++ b/PSWriteColor.psd1 @@ -8,7 +8,7 @@ Description = 'Write-Color is a wrapper around Write-Host allowing you to create nice looking scripts, with colorized output. It provides easy manipulation of colors, logging output to file (log) and nice formatting options out of the box.' FunctionsToExport = 'Write-Color' GUID = '0b0ba5c5-ec85-4c2b-a718-874e55a8bc3f' - ModuleVersion = '1.0.4' + ModuleVersion = '1.0.5' PowerShellVersion = '5.1' PrivateData = @{ PSData = @{ diff --git a/Public/Write-Color.ps1 b/Public/Write-Color.ps1 index dd59b49..9591adf 100644 --- a/Public/Write-Color.ps1 +++ b/Public/Write-Color.ps1 @@ -63,6 +63,14 @@ function Write-Color { .PARAMETER NoConsoleOutput Switch to not output to console. Default all output goes to console. + .PARAMETER OutputStream + Destination for messages: Host (default), Verbose, or Information. + Verbose and Information emit one joined text record per call and respect their + normal PowerShell preferences. Use -Verbose or -InformationAction Continue to display them. + ShowTime is supported; console colors, padding, indentation, blank lines, centering, + and NoNewLine apply only to Host. NoConsoleOutput suppresses any selected message + stream while retaining file logging. No messages are written to success output. + .PARAMETER HorizontalCenter Centers single-line text, including its padding, in the visible host window. Odd extra space goes on the right. Indentation and timestamps are added after centering. If the host cannot report its window width, no centering spaces are added. @@ -157,7 +165,8 @@ function Write-Color { [alias('PL')][ValidateRange(0, [int]::MaxValue)][int] $PadLeft = 0, [alias('PC')][ValidateRange(0, [int]::MaxValue)][int] $PadCenter = 0, [alias('PR')][ValidateRange(0, [int]::MaxValue)][int] $PadRight = 0, - [alias('PadChar')][char] $PadCharacter = ' ' + [alias('PadChar')][char] $PadCharacter = ' ', + [ValidateSet('Host', 'Verbose', 'Information')][string] $OutputStream = 'Host' ) if (@($PadLeft, $PadCenter, $PadRight | Where-Object { $_ -gt 0 }).Count -gt 1) { throw 'Specify only one of PadLeft, PadCenter, or PadRight with a positive width.' @@ -169,7 +178,18 @@ function Write-Color { # Handle Ignore at this boundary: Windows PowerShell 5.1 cannot pass an inherited # Ignore preference through to nested Write-Host calls. $SuppressConsole = $NoConsoleOutput -or $PSBoundParameters['InformationAction'] -eq [System.Management.Automation.ActionPreference]::Ignore - if (-not $SuppressConsole) { + if (-not $NoConsoleOutput -and $OutputStream -ne 'Host') { + $Message = $TextToFile + if ($ShowTime) { + $Message = "[$([datetime]::Now.ToString($DateTimeFormat))] $Message" + } + if ($OutputStream -eq 'Verbose') { + Write-Verbose -Message $Message + } elseif (-not $SuppressConsole) { + Write-Information -MessageData $Message -Tags 'WriteColor' + } + } + if (-not $SuppressConsole -and $OutputStream -eq 'Host') { if ($null -eq $Color -or $Color.Count -eq 0) { Write-Error 'Color must contain at least one foreground color.' return diff --git a/README.md b/README.md index 35e11f2..8378298 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,26 @@ Write-Color is a wrapper around Write-Host allowing you to create nice looking scripts, with colorized output. More information for this project at my [Evotec website](https://evotec.xyz/hub/scripts/pswritecolor/). +## Messages in automation + +`Write-Color` uses colored host output by default. Select a diagnostic stream when +running in an environment that captures PowerShell messages instead of a console: + +```powershell +Write-Color 'Processing ', '25', ' contacts' -OutputStream Verbose -Verbose +Write-Color 'Processing ', '25', ' contacts' -OutputStream Information -InformationAction Continue +``` + +Each call writes one joined message to the selected stream, leaving success output +available for returned objects. Verbose and Information follow normal PowerShell +preferences. Azure Automation requires verbose job logging to retain Verbose records. +Information stream capture depends on the host. + +`-ShowTime` adds a timestamp to either message stream. Colors, indentation, padding, +blank lines, centering, and `-NoNewLine` apply to Host output only. `-NoConsoleOutput` +suppresses the selected message stream; `-LogFile` still appends the text to the file. +No host detection changes the stream automatically. + ## Support This Project If you find this project helpful, please consider supporting its development. diff --git a/Tests/Write-Color.Streams.Tests.ps1 b/Tests/Write-Color.Streams.Tests.ps1 new file mode 100644 index 0000000..be3893d --- /dev/null +++ b/Tests/Write-Color.Streams.Tests.ps1 @@ -0,0 +1,48 @@ +param( + [string] $ModulePath = (Join-Path $PSScriptRoot '../PSWriteColor.psd1') +) + +BeforeAll { + Get-Module PSWriteColor | Remove-Module -Force + Import-Module $ModulePath -Force +} + +Describe 'Write-Color message streams' { + It 'emits a complete verbose record without success output' { + $records = @(Write-Color 'one', 'two' -OutputStream Verbose -Verbose 4>&1) + $records.Count | Should -Be 1 + $records[0] | Should -BeOfType ([System.Management.Automation.VerboseRecord]) + $records[0].Message | Should -BeExactly 'onetwo' + @(Write-Color 'hidden' -OutputStream Verbose -Verbose:$false 4>&1).Count | Should -Be 0 + } + + It 'emits a complete tagged information record and honors suppression' { + $records = @(Write-Color 'one', 'two' -OutputStream Information -InformationAction Continue 6>&1) + $records.Count | Should -Be 1 + $records[0] | Should -BeOfType ([System.Management.Automation.InformationRecord]) + $records[0].MessageData | Should -BeExactly 'onetwo' + $records[0].Tags | Should -Contain 'WriteColor' + @(Write-Color 'hidden' -OutputStream Information -InformationAction Ignore 6>&1).Count | Should -Be 0 + } + + It 'keeps file logging when the selected stream is suppressed' -ForEach @( + @{ Stream = 'Verbose' }, @{ Stream = 'Information' } + ) { + $log = Join-Path $TestDrive "$Stream.log" + $records = @(Write-Color 'one', 'two' -OutputStream $Stream -NoConsoleOutput -Verbose -InformationAction Continue -LogFile $log -LogTime $false *>&1) + $records.Count | Should -Be 0 + Get-Content -LiteralPath $log | Should -BeExactly 'onetwo' + } + + It 'uses timestamps but ignores terminal layout for record streams' { + $records = @(Write-Color 'text' -OutputStream Verbose -Verbose -ShowTime -DateTimeFormat "'time'" -StartTab 2 -StartSpaces 2 -PadRight 20 -LinesBefore 2 -LinesAfter 2 -HorizontalCenter -NoNewLine 4>&1) + $records.Count | Should -Be 1 + $records[0].Message | Should -BeExactly '[time] text' + } + + It 'does not let information suppression silence the verbose stream' { + $records = @(Write-Color 'text' -OutputStream Verbose -Verbose -InformationAction Ignore 4>&1) + $records.Count | Should -Be 1 + $records[0].Message | Should -BeExactly 'text' + } +} diff --git a/en-US/PSWriteColor-help.xml b/en-US/PSWriteColor-help.xml index 27c2e44..bee62fa 100644 --- a/en-US/PSWriteColor-help.xml +++ b/en-US/PSWriteColor-help.xml @@ -217,6 +217,28 @@ File-write failures produce warnings after up to LogRetry attempts. False + + + OutputStream + + Destination for messages: Host (default), Verbose, or Information. +Verbose and Information emit one joined text record per call and respect their +normal PowerShell preferences. Use -Verbose or -InformationAction Continue to display them. +ShowTime is supported; console colors, padding, indentation, blank lines, centering, +and NoNewLine apply only to Host. NoConsoleOutput suppresses any selected message +stream while retaining file logging. No messages are written to success output. + + String + + Host + Verbose + Information + + + String + + + Host PadCenter @@ -521,6 +543,28 @@ File-write failures produce warnings after up to LogRetry attempts. False + + OutputStream + + Destination for messages: Host (default), Verbose, or Information. +Verbose and Information emit one joined text record per call and respect their +normal PowerShell preferences. Use -Verbose or -InformationAction Continue to display them. +ShowTime is supported; console colors, padding, indentation, blank lines, centering, +and NoNewLine apply only to Host. NoConsoleOutput suppresses any selected message +stream while retaining file logging. No messages are written to success output. + + String + + Host + Verbose + Information + + + String + + + Host + PadCenter