From 90b9953ba5d431e90b08d3f855ce120d7513a52f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Przemys=C5=82aw=20K=C5=82ys?= Date: Tue, 6 Oct 2026 09:25:51 +0200 Subject: [PATCH] Add explicit success-output messages for automation --- Docs/Readme.md | 2 +- Docs/Write-Color.md | 46 +++++++------- PSWriteColor.psd1 | 4 +- Public/Write-Color.ps1 | 12 ++-- README.md | 17 +++--- Tests/Write-Color.Streams.Tests.ps1 | 24 ++++++-- en-US/PSWriteColor-help.xml | 94 +++++++++++++++-------------- 7 files changed, 115 insertions(+), 84 deletions(-) diff --git a/Docs/Readme.md b/Docs/Readme.md index 7576a33..1df4cf0 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.5 +Help Version: 1.0.6 Locale: en-US --- # PSWriteColor Module diff --git a/Docs/Write-Color.md b/Docs/Write-Color.md index d9b0e69..4c5b093 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] ] [[-OutputStream] ] [-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,27 +294,29 @@ 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 -``` - +### -OutputStream +Destination for messages: Host (default), Output, Verbose, or Information. +Output emits one joined string per call on the success stream, so assignments +and pipelines capture these messages as data. Use it for Azure Automation job output. +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. Only Output writes messages to success output. + +```yaml +Type: String +Parameter Sets: __AllParameterSets +Aliases: None +Possible values: Host, Output, 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 dbb4214..fa3464e 100644 --- a/PSWriteColor.psd1 +++ b/PSWriteColor.psd1 @@ -1,4 +1,4 @@ -@{ +@{ AliasesToExport = @('Write-Colour') Author = 'Przemyslaw Klys' CmdletsToExport = @() @@ -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.5' + ModuleVersion = '1.0.6' PowerShellVersion = '5.1' PrivateData = @{ PSData = @{ diff --git a/Public/Write-Color.ps1 b/Public/Write-Color.ps1 index 9591adf..9e29f96 100644 --- a/Public/Write-Color.ps1 +++ b/Public/Write-Color.ps1 @@ -64,12 +64,14 @@ function Write-Color { Switch to not output to console. Default all output goes to console. .PARAMETER OutputStream - Destination for messages: Host (default), Verbose, or Information. + Destination for messages: Host (default), Output, Verbose, or Information. + Output emits one joined string per call on the success stream, so assignments + and pipelines capture these messages as data. Use it for Azure Automation job output. 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. + stream while retaining file logging. Only Output writes messages to success output. .PARAMETER HorizontalCenter Centers single-line text, including its padding, in the visible host window. Odd extra space goes on the right. @@ -166,7 +168,7 @@ function Write-Color { [alias('PC')][ValidateRange(0, [int]::MaxValue)][int] $PadCenter = 0, [alias('PR')][ValidateRange(0, [int]::MaxValue)][int] $PadRight = 0, [alias('PadChar')][char] $PadCharacter = ' ', - [ValidateSet('Host', 'Verbose', 'Information')][string] $OutputStream = 'Host' + [ValidateSet('Host', 'Output', '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.' @@ -183,7 +185,9 @@ function Write-Color { if ($ShowTime) { $Message = "[$([datetime]::Now.ToString($DateTimeFormat))] $Message" } - if ($OutputStream -eq 'Verbose') { + if ($OutputStream -eq 'Output') { + Write-Output -InputObject $Message + } elseif ($OutputStream -eq 'Verbose') { Write-Verbose -Message $Message } elseif (-not $SuppressConsole) { Write-Information -MessageData $Message -Tags 'WriteColor' diff --git a/README.md b/README.md index 8378298..1d5deaa 100644 --- a/README.md +++ b/README.md @@ -24,20 +24,23 @@ More information for this project at my [Evotec website](https://evotec.xyz/hub/ ## Messages in automation -`Write-Color` uses colored host output by default. Select a diagnostic stream when +`Write-Color` uses colored host output by default. Select a message stream when running in an environment that captures PowerShell messages instead of a console: ```powershell +Write-Color 'Processing ', '25', ' contacts' -OutputStream Output 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. +Each call writes one joined message to the selected stream. `Output` writes a plain +string to the success stream and works with Azure Automation job output without +enabling verbose logging. Assignments and pipelines capture these strings as data. +Verbose and Information leave success output available for returned objects and +follow normal PowerShell preferences. Azure Automation requires verbose job logging +to retain Verbose records and does not support the Information stream. -`-ShowTime` adds a timestamp to either message stream. Colors, indentation, padding, +`-ShowTime` adds a timestamp to message streams. 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. @@ -104,7 +107,7 @@ Import-Module PSWriteColor `Write-Color` joins the supplied text segments without inserting separators and writes each segment with its assigned color. When there are fewer colors than segments, the remaining segments use the first color. Background colors, when supplied, must have the same count as foreground colors. `Write-Colour` is an alias; `wc` is not exported. -The command writes host output on PowerShell's information stream and returns no objects on the success pipeline. Use it for status messages and prompts, rather than data that another command needs to process. `-NoNewLine` lets the next message continue on the same console line. +By default, the command writes host output on PowerShell's information stream and returns no objects on the success pipeline. Use it for status messages and prompts. `-OutputStream Output` returns plain message strings on the success pipeline. `-NoNewLine` lets the next host message continue on the same console line. `-LogFile` appends the original joined text to a literal filename, optionally prefixed with a timestamp. Console spacing, padding, and `-NoNewLine` do not change log entries. Parent directories must exist. `-LogRetry` is the maximum number of attempts, including the first; exhausted attempts produce warnings. Logging still runs under `$WhatIfPreference`, and `-NoConsoleOutput` suppresses only console output. diff --git a/Tests/Write-Color.Streams.Tests.ps1 b/Tests/Write-Color.Streams.Tests.ps1 index be3893d..7e3e4b8 100644 --- a/Tests/Write-Color.Streams.Tests.ps1 +++ b/Tests/Write-Color.Streams.Tests.ps1 @@ -8,6 +8,20 @@ BeforeAll { } Describe 'Write-Color message streams' { + It 'emits one plain success string without enabling diagnostic preferences' { + $records = @(Write-Color 'one', 'two' -OutputStream Output -Verbose:$false -InformationAction Ignore *>&1) + $records.Count | Should -Be 1 + $records[0] | Should -BeOfType ([string]) + $records[0] | Should -BeExactly 'onetwo' + } + + It 'writes the same joined text to output and the log file' { + $log = Join-Path $TestDrive 'output-and-file.log' + $records = @(Write-Color 'one', 'two' -OutputStream Output -LogFile $log -LogTime $false) + $records | Should -BeExactly 'onetwo' + Get-Content -LiteralPath $log | Should -BeExactly 'onetwo' + } + It 'emits a complete verbose record without success output' { $records = @(Write-Color 'one', 'two' -OutputStream Verbose -Verbose 4>&1) $records.Count | Should -Be 1 @@ -26,7 +40,7 @@ Describe 'Write-Color message streams' { } It 'keeps file logging when the selected stream is suppressed' -ForEach @( - @{ Stream = 'Verbose' }, @{ Stream = 'Information' } + @{ Stream = 'Output' }, @{ 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) @@ -34,10 +48,12 @@ Describe 'Write-Color message streams' { 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) + It 'uses timestamps but ignores terminal layout for messages' -ForEach @( + @{ Stream = 'Output' }, @{ Stream = 'Verbose' }, @{ Stream = 'Information' } + ) { + $records = @(Write-Color 'text' -OutputStream $Stream -Verbose -InformationAction Continue -ShowTime -DateTimeFormat "'time'" -StartTab 2 -StartSpaces 2 -PadRight 20 -LinesBefore 2 -LinesAfter 2 -HorizontalCenter -NoNewLine *>&1) $records.Count | Should -Be 1 - $records[0].Message | Should -BeExactly '[time] text' + "$($records[0])" | Should -BeExactly '[time] text' } It 'does not let information suppression silence the verbose stream' { diff --git a/en-US/PSWriteColor-help.xml b/en-US/PSWriteColor-help.xml index bee62fa..ac5d053 100644 --- a/en-US/PSWriteColor-help.xml +++ b/en-US/PSWriteColor-help.xml @@ -217,28 +217,31 @@ 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 + + + OutputStream + + Destination for messages: Host (default), Output, Verbose, or Information. +Output emits one joined string per call on the success stream, so assignments +and pipelines capture these messages as data. Use it for Azure Automation job output. +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. Only Output writes messages to success output. + + String + + Host + Output + Verbose + Information + + + String + + + Host PadCenter @@ -543,28 +546,31 @@ 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 - + + OutputStream + + Destination for messages: Host (default), Output, Verbose, or Information. +Output emits one joined string per call on the success stream, so assignments +and pipelines capture these messages as data. Use it for Azure Automation job output. +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. Only Output writes messages to success output. + + String + + Host + Output + Verbose + Information + + + String + + + Host + PadCenter