Add opt-in diagnostic streams to Write-Color

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

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] <string[]>] [[-Color] <ConsoleColor[]>] [[-BackGroundColor] <ConsoleColor[]>] [[-StartTab] <int>] [[-LinesBefore] <int>] [[-LinesAfter] <int>] [[-StartSpaces] <int>] [[-LogFile] <string>] [[-DateTimeFormat] <string>] [[-LogTime] <bool>] [[-LogRetry] <int>] [[-Encoding] <string>] [[-PadLeft] <int>] [[-PadCenter] <int>] [[-PadRight] <int>] [[-PadCharacter] <char>] [-ShowTime] [-NoNewLine] [-HorizontalCenter] [-NoConsoleOutput] [<CommonParameters>]
+Write-Color [[-Text] <string[]>] [[-Color] <ConsoleColor[]>] [[-BackGroundColor] <ConsoleColor[]>] [[-StartTab] <int>] [[-LinesBefore] <int>] [[-LinesAfter] <int>] [[-StartSpaces] <int>] [[-LogFile] <string>] [[-DateTimeFormat] <string>] [[-LogTime] <bool>] [[-LogRetry] <int>] [[-Encoding] <string>] [[-PadLeft] <int>] [[-PadCenter] <int>] [[-PadRight] <int>] [[-PadCharacter] <char>] [[-OutputStream] <string>] [-ShowTime] [-NoNewLine] [-HorizontalCenter] [-NoConsoleOutput] [<CommonParameters>]
 ```
 
 ## 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.
 

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 = @{

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

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.

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'
+    }
+}

en-US/PSWriteColor-help.xml

@@ -217,6 +217,28 @@ File-write failures produce warnings after up to LogRetry attempts.</maml:para>
             <maml:uri />
           </dev:type>
           <dev:defaultValue>False</dev:defaultValue>
+        </command:parameter>
+        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="16" aliases="none">
+          <maml:name>OutputStream</maml:name>
+          <maml:description>
+            <maml:para>Destination for messages: Host (default), Verbose, or Information.&#xD;
+Verbose and Information emit one joined text record per call and respect their&#xD;
+normal PowerShell preferences. Use -Verbose or -InformationAction Continue to display them.&#xD;
+ShowTime is supported; console colors, padding, indentation, blank lines, centering,&#xD;
+and NoNewLine apply only to Host. NoConsoleOutput suppresses any selected message&#xD;
+stream while retaining file logging. No messages are written to success output.</maml:para>
+          </maml:description>
+          <command:parameterValue required="false" variableLength="false">String</command:parameterValue>
+          <command:parameterValueGroup>
+            <command:parameterValue required="false" variableLength="false">Host</command:parameterValue>
+            <command:parameterValue required="false" variableLength="false">Verbose</command:parameterValue>
+            <command:parameterValue required="false" variableLength="false">Information</command:parameterValue>
+          </command:parameterValueGroup>
+          <dev:type>
+            <maml:name>String</maml:name>
+            <maml:uri />
+          </dev:type>
+          <dev:defaultValue>Host</dev:defaultValue>
         </command:parameter>
         <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="13" aliases="PC">
           <maml:name>PadCenter</maml:name>
@@ -521,6 +543,28 @@ File-write failures produce warnings after up to LogRetry attempts.</maml:para>
         </dev:type>
         <dev:defaultValue>False</dev:defaultValue>
       </command:parameter>
+      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="16" aliases="none">
+        <maml:name>OutputStream</maml:name>
+        <maml:description>
+          <maml:para>Destination for messages: Host (default), Verbose, or Information.&#xD;
+Verbose and Information emit one joined text record per call and respect their&#xD;
+normal PowerShell preferences. Use -Verbose or -InformationAction Continue to display them.&#xD;
+ShowTime is supported; console colors, padding, indentation, blank lines, centering,&#xD;
+and NoNewLine apply only to Host. NoConsoleOutput suppresses any selected message&#xD;
+stream while retaining file logging. No messages are written to success output.</maml:para>
+        </maml:description>
+        <command:parameterValue required="false" variableLength="false">String</command:parameterValue>
+        <command:parameterValueGroup>
+          <command:parameterValue required="false" variableLength="false">Host</command:parameterValue>
+          <command:parameterValue required="false" variableLength="false">Verbose</command:parameterValue>
+          <command:parameterValue required="false" variableLength="false">Information</command:parameterValue>
+        </command:parameterValueGroup>
+        <dev:type>
+          <maml:name>String</maml:name>
+          <maml:uri />
+        </dev:type>
+        <dev:defaultValue>Host</dev:defaultValue>
+      </command:parameter>
       <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="13" aliases="PC">
         <maml:name>PadCenter</maml:name>
         <maml:description>