Skip to content

Support plain output messages in Azure Automation #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PrzemyslawKlys merged 1 commit into from
Oct 6, 2026
Merged

Support plain output messages in Azure Automation #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Docs/Readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
46 changes: 24 additions & 22 deletions Docs/Write-Color.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>] [[-OutputStream] <string>] [-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
Expand Down Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions PSWriteColor.psd1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
@{
@{
AliasesToExport = @('Write-Colour')
Author = 'Przemyslaw Klys'
CmdletsToExport = @()
Expand All @@ -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 = @{
Expand Down
12 changes: 8 additions & 4 deletions Public/Write-Color.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.'
Expand All @@ -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'
Expand Down
17 changes: 10 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down
24 changes: 20 additions & 4 deletions Tests/Write-Color.Streams.Tests.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -26,18 +40,20 @@ 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)
$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)
It 'uses timestamps but ignores terminal layout for <Stream> 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' {
Expand Down
94 changes: 50 additions & 44 deletions en-US/PSWriteColor-help.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,28 +217,31 @@ 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="16" aliases="none">
<maml:name>OutputStream</maml:name>
<maml:description>
<maml:para>Destination for messages: Host (default), Output, Verbose, or Information.&#xD;
Output emits one joined string per call on the success stream, so assignments&#xD;
and pipelines capture these messages as data. Use it for Azure Automation job output.&#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. Only Output writes messages 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">Output</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>
Expand Down Expand Up @@ -543,28 +546,31 @@ 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="16" aliases="none">
<maml:name>OutputStream</maml:name>
<maml:description>
<maml:para>Destination for messages: Host (default), Output, Verbose, or Information.&#xD;
Output emits one joined string per call on the success stream, so assignments&#xD;
and pipelines capture these messages as data. Use it for Azure Automation job output.&#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. Only Output writes messages 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">Output</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>
Expand Down
Loading