Cmdlet

Write-ConsoleText

Module ConsoleMonster

Inputs

System.Object[]

Writes multicolour text to the console and, optionally, to a log file: Write-Color compatible, with markup, styles, gradients, padding, wrapping and structured logs.

Syntax

Write-ConsoleText [-BackGroundColor <Object[]>] [-Category <String>] [-Color <Object[]>] [-DateTimeFormat <String>] [-Encoding <String>] [-Gradient <Object[]>] [-HorizontalCenter] [-Level <String>] [-LinesAfter <Int32>] [-LinesBefore <Int32>] [-Link <String>] [-LogFile <String>] [-LogFormat <Text|Csv|JsonLines>] [-LogRetry <Int32>] [-LogSeparator <String>] [-LogTime <Boolean>] [-Markup <String>] [-NoConsoleOutput] [-NoNewLine] [-PadCenter <Int32>] [-PadCharacter <Char>] [-PadLeft <Int32>] [-PadRight <Int32>] [-Role <ThemeToken>] [-ShowTime] [-SplitLines <String>] [-StartSpaces <Int32>] [-StartTab <Int32>] [-Style <String[]>] [[-Text] <Object[]>] [-Width <Int32>] [-Wrap] [<CommonParameters>]

Parameter set: All Parameter Sets

Description

Writes multicolour text to the console and, optionally, to a log file: Write-Color compatible, with markup, styles, gradients, padding, wrapping and structured logs.

The parameters and aliases of Write-Color (PSWriteColor) work the same way: -Text pieces get -Color and -BackGroundColor per piece (pieces beyond the colours use the first colour), -StartTab, -StartSpaces, -LinesBefore, -LinesAfter, -ShowTime with -DateTimeFormat, -NoNewLine, -HorizontalCenter, -LogFile with -LogTime, -LogRetry and -Encoding, and -NoConsoleOutput. ConsoleColor names render exactly as Write-Host shows them. Beyond Write-Color: -Markup, -Style, -Link, -Role, hex and RGB colours, -Gradient, -PadLeft/-PadRight/-PadCenter with -PadCharacter (measured in terminal cells, so emoji and CJK pad correctly), -Wrap with a hanging indent under the time and prefix, -SplitLines with the following lines aligned under the first, and -LogFormat Text, Csv or JsonLines with -LogSeparator, -Level and -Category. Differences: the default colour is the terminal's own (Write-Color uses White), and a new log file is UTF-8 without a byte order mark by default (Write-Color writes UTF-16); appending to an existing log keeps its encoding, so Write-Color's UTF-16 logs stay UTF-16. In transcripts each call is one line; in jobs and remoting the colours travel with the output; redirected output is plain text. There is deliberately no Write-Color or wc alias.

Examples

Authored help example

EXAMPLE 1

Write-ConsoleText -BackGroundColor @('Value')

Parameters

-BackGroundColor Object[] optionalaliases: B, BGC: Background colour per piece.
-Category String optional: A category for the log record.
-Color Object[] optionalaliases: C, FGC, ForegroundColor: Foreground colour per piece: ConsoleColor names (exactly as Write-Host shows them: DarkRed is ANSI red, Red bright red; grey spells Gray), theme roles, #RRGGBB, rgb(r,g,b), r,g,b, or a markup palette name (cadetblue; palette.darkred for the palette colour where the bare name is a ConsoleColor).
-DateTimeFormat String optionalaliases: DateFormat, TimeFormat: The time format for -ShowTime and the log (default yyyy-MM-dd HH:mm:ss).
-Encoding String optional: The encoding of a new log file: utf8 without a byte order mark by default (Write-Color defaults to unicode, which is UTF-16 LE); Write-Color's names mean the same here (unicode, string and unknown are UTF-16 LE, bigendianunicode UTF-16 BE, utf32 UTF-32 LE), plus utf8BOM and utf8NoBOM. Appending to an existing file always keeps that file's encoding (detected from its byte order mark, or UTF-16 text without one), so a UTF-16 log from Write-Color stays UTF-16; when -Encoding names a different one, a warning says so.; Possible values: unknown, string, unicode, bigendianunicode, utf8, utf8BOM, utf8NoBOM, utf7, utf32, ascii, default, oem
-Gradient Object[] optional: Two colours: the text is coloured from the first to the second (per character; steps on 16-colour terminals).
-HorizontalCenter SwitchParameter optional: Centres each line in the window (measured in terminal cells, so emoji and CJK centre correctly).
-Level String optional: A level for the log record (Info, Warning, Error...).
-LinesAfter Int32 optional: Empty lines after the text.
-LinesBefore Int32 optional: Empty lines before the text.
-Link String optional: A hyperlink target for the whole text (OSC 8 where supported).
-LogFile String optionalaliases: L: A log file the text is appended to (plain text, see -LogFormat).
-LogFormat String optional: The log format: Text (the Write-Color layout), Csv or JsonLines.; Possible values: Text, Csv, JsonLines
-LogRetry Int32 optional: Attempts to write the log file before giving up with a warning (default 2).
-LogSeparator String optional: The CSV separator (default a comma).
-LogTime Boolean optionalaliases: LogTimeStamp: Whether log lines start with the time (default $true).
-Markup String optional: Markup added after the pieces ([bold lime]Ready[/] in [muted]3s[/]).
-NoConsoleOutput SwitchParameter optionalaliases: HideConsole: Writes only to the log file.
-NoNewLine SwitchParameter optional: Leaves the line open, so the next output continues on it.
-PadCenter Int32 optional: Centres the text within this many cells.
-PadCharacter Char optional: The padding character (default a space).
-PadLeft Int32 optional: Pads the text on the left to this many cells (right-aligned).
-PadRight Int32 optional: Pads the text on the right to this many cells.
-Role ThemeToken optional: A theme role for pieces without their own colour (Pass, Fail, Warn, Info, Muted, Accent...).; Possible values: Text, Muted, Subtle, Accent, Accent2, Pass, Fail, Warn, Info, Skip, Running, Pending, Border, Title, Header, Highlight, Surface, SurfaceAccent, Series1, Series2, Series3, Series4, Series5, Series6, Focus
-ShowTime SwitchParameter optional: Starts the line with the time in brackets.
-SplitLines String optional: Splits the text at this separator; the following lines are aligned under the first, after the time and prefix.
-StartSpaces Int32 optional: Spaces before the text.
-StartTab Int32 optionalaliases: Indent: Tabs before the text (eight cells each).
-Style String[] optional: Decorations for the whole text: Bold, Dim, Italic, Underline, Strikethrough, Invert.
-Text Object[] optionalposition: 0pipeline: True (ByValue)aliases: T: Text pieces, shown literally (strings, or rich text from New-ConsoleText).
-Width Int32 optional: The width for -Wrap and -HorizontalCenter (default the window width).
-Wrap SwitchParameter optional: Wraps long text at the window width, continuing under the text after the time and prefix.

Common Parameters

This command supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.

For more information, see about_CommonParameters.