PowerShell function named Write-Section that prints/writes/outputs messages to the console surrounded by a decorative hash border ( # character). It improves console readability and supports multiple message types such as warnings, debug, verbose, and information. The function also features graceful word wrapping to fit within the console width.

README.md

Write-Section PowerShell Function

Preference variables not required (see below).

The Write-Section function is a custom PowerShell function designed to enhance the readability of console output. It prints text messages surrounded by a section divider made up of hash # characters. This effectively gives a border to your PowerShell output.

Features

• Border: Provides a decorative border around your text for better visibility.
• Stand Out: Easy way to separate messages that you want to stand out.
• Customizable Message Types: Supports various message types including:
  • Warnings
  • Debug
  • Information
  • Verbose
  • Output
• Graceful Word Wrapping: Automatically wraps messages to fit within the console width without cutting off any characters.
• Fully Enclosed Text: Pads messages so that the # character appears before and after the messages lines
• Readability: Enhances the readability of your PowerShell console output.

Parameters

Parameter	Required	Description
Message	Yes, default parameter if not specified explicitly	The message to be printed within the section divider.
Type	No	The type of message to display; defaults to Output.

Type Values

Type Value	Description
Warning	Displays the message using Write-Warning.
Debug	Displays the message using Write-Debug.
Information	Displays the message using Write-Information.
Verbose	Displays the message using Write-Verbose.
Output	Displays the message using Write-Output (default).

Unfortunately Write-Error is not supported in this function because it outputs a stack trace and would cause issues with the formatting.

Examples

Preference Variables

If you want to test with Debug/Verbose/Warning, you'll have to set these variables to Continue. Otherwise you'll have to use the -Debug, -Verbose, etc. arguments when launching a script that supports CmdletBinding(). More about preference variables in PowerShell.

$VerbosePreference = 'Continue'
$DebugPreference = 'Continue'
$InformationPreference = 'Continue'

For basic usage you do not need the above variable assignments.

---

Example Commands

# Basic usage
Write-Section -Message "This is a basic message."

# Using a warning type
Write-Section -Message "This is a warning message." -Type "Warning"

# Using an information type
Write-Section -Message "This is an information message." -Type "Information"

# Using a debug type
Write-Section -Message "This is a debug message." -Type "Debug"

# Using a verbose type
Write-Section -Message "This is a verbose message." -Type "Verbose"

# Implicit use of the Message parameter
Write-Section "Implicit message parameter example. You can provide the message without explicitly naming the Message parameter, making the function even more convenient to use."

# Additional Implicit use of the Message parameter and Type of Debug
Write-Section "Additional implicit message parameter example. You can provide the message without explicitly naming the Message parameter, making the function even more convenient to use, while still specifying the type." -Type "Debug"

---

Example Output (Respectively)

######################################################################################################################
# This is a basic message.                                                                                            #
######################################################################################################################

WARNING: #############################################################################################################
WARNING: # This is a warning message.                                                                                #
WARNING: #############################################################################################################

######################################################################################################################
# This is an information message.                                                                                    #
######################################################################################################################

DEBUG: ###############################################################################################################
DEBUG: # This is a debug message.                                                                                    #
DEBUG: ###############################################################################################################

VERBOSE: #############################################################################################################
VERBOSE: # This is a verbose message.                                                                                #
VERBOSE: #############################################################################################################

######################################################################################################################
# Implicit message parameter example. You can provide the message without explicitly naming the Message parameter,   #
# making the function even more convenient to use.                                                                   #
######################################################################################################################

DEBUG: ###############################################################################################################
DEBUG: # Additional implicit message parameter example. You can provide the message without explicitly naming the    #
DEBUG: # Message parameter, making the function even more convenient to use, while still specifying the type.        #
DEBUG: ###############################################################################################################

PS-Write-Section.ps1

function Write-Section {
    <#
        .SYNOPSIS
        Prints a text block surrounded by a section divider for enhanced output readability.

        .DESCRIPTION
        This function takes a message input and prints it to the console, surrounded by a section divider made of hash characters.
        It enhances the readability of console output by categorizing messages based on the Type parameter.

        .PARAMETER Message
        The message to be printed within the section divider. This parameter is mandatory.

        .PARAMETER Type
        The type of message to display. Possible values: "Output" (default), "Debug," "Warning," "Information," "Verbose."

        .EXAMPLE
        Write-Section -Message "This is a sample message."

        This command prints the provided message surrounded by a section divider. Because the Type parameter is not specified, it defaults to "Output."

        .EXAMPLE
        Write-Section "This is another sample message."

        This command also prints the message surrounded by a section divider. The -Message parameter is implied and does not need to be explicitly named.

        .EXAMPLE
        Write-Section -Message "This is a warning message." -Type "Warning"

        This command prints the provided message surrounded by a section divider and uses Write-Warning to display the message, due to the Type parameter being set to "Warning."
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [string]$Message,
        [ValidateSet("Output", "Debug", "Warning", "Information", "Verbose")]
        [string]$Type = "Output"
    )

    $consoleWidth = [System.Console]::WindowWidth - 2
    $prependLength = 0

    switch ($Type) {
        "Output" { $writeCmd = { Write-Output $args[0] } }
        "Debug" { $writeCmd = { Write-Debug $args[0] }; $prependLength = 7 }
        "Warning" { $writeCmd = { Write-Warning $args[0] }; $prependLength = 9 }
        "Information" { $writeCmd = { Write-Information $args[0] }; }
        "Verbose" { $writeCmd = { Write-Verbose $args[0] }; $prependLength = 9 }
    }

    $divider = "#" * ($consoleWidth - $prependLength)
    & $writeCmd $divider

    $words = $Message -split ' '
    $line = "# "
    foreach ($word in $words) {
        if (($line.Length + $word.Length + 1) -gt ($consoleWidth - $prependLength - 1)) {
            $line = $line.PadRight($consoleWidth - $prependLength - 1) + "#"
            & $writeCmd $line
            $line = "# "
        }
        $line += "$word "
    }

    if ($line.Trim().Length -gt 1) {
        $line = $line.PadRight($consoleWidth - $prependLength - 1) + "#"
        & $writeCmd $line
    }

    $divider = "#" * ($consoleWidth - $prependLength)
    & $writeCmd $divider
}