< Back

Write-PSFMessage

Sun Jan 19, 2020 6:46 pm

NAME Write-PSFMessage



SYNOPSIS

This function receives messages, then logs and reports them.





SYNTAX

Write-PSFMessage [-Level <MessageLevel>] -Message <String> [-Tag <String[]>] [-FunctionName <String>] [-ModuleName

<String>] [-File <String>] [-Line <Int32>] [-ErrorRecord <ErrorRecord[]>] [-Exception <Exception>] [-Once

<String>] [-OverrideExceptionMessage] [-Target <Object>] [-EnableException <Boolean>] [-Breakpoint]

[<CommonParameters>]



Write-PSFMessage [-Level <MessageLevel>] [-Tag <String[]>] [-FunctionName <String>] [-ModuleName <String>] [-File

<String>] [-Line <Int32>] [-ErrorRecord <ErrorRecord[]>] [-Exception <Exception>] [-Once <String>]

[-OverrideExceptionMessage] [-Target <Object>] [-EnableException <Boolean>] [-Breakpoint] -String <String>

[-StringValues <Object[]>] [<CommonParameters>]





DESCRIPTION

This function receives messages, then logs and reports them. It is designed to fully replace most Write-*

commands, such as Write-Verbose or Write-Warning. Messages can be retrieved after the fact - whether they were

shown on screen or not - using Get-PSFMessage. This includes messages written in other runspaces. All messages are

logged in a runspace-safe manner, preventing write conflicts.



This function will handle:



- Warning output



- Error management for non-terminating errors (For errors that terminate execution or continue on with the next

object use "Stop-PSFFunction")



- Logging



- Verbose output



- Message output to users



For the complex description on how this works and how users and developers can influence it, run: Get-Help

about_psf_message





PARAMETERS

-Level <MessageLevel>

This parameter represents the verbosity of the message. The lower the number, the more important it is for a

human user to read the message. By default, the levels are distributed like this:



- 1-3 Direct verbose output to the user (using Write-Host)



- 4-6 Output only visible when requesting extra verbosity (using Write-Verbose)



- 1-9 Debugging information, written using Write-Debug



In addition, it is possible to select the level "Warning" which moves the message out of the configurable

range: The user will always be shown this message, unless he silences the entire verbosity.



Possible levels: Critical (1), Important / Output / Host (2), Significant (3), VeryVerbose (4), Verbose (5),

SomewhatVerbose (6), System (7), Debug (8), InternalComment (9), Warning (666) Either one of the strings or

its respective number will do as input.



Required? false

Position? named

Default value [PSFramework.Message.MessageLevel]::Verbose

Accept pipeline input? False

Accept wildcard characters? false



-Message <String>

The message to write/log. The function name and timestamp will automatically be prepended.



Required? true

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-Tag <String[]>

Tags to add to the message written. This allows filtering and grouping by category of message, targeting

specific messages.



Required? false

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-FunctionName <String>

The name of the calling function. Will be automatically set, but can be overridden when necessary.



Required? false

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-ModuleName <String>

The name of the module, the calling function is part of. Will be automatically set, but can be overridden when

necessary.



Required? false

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-File <String>

The file in which Write-PSFMessage was called. Will be automatically set, but can be overridden when necessary.



Required? false

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-Line <Int32>

The line on which Write-PSFMessage was called. Will be automatically set, but can be overridden when necessary.



Required? false

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-ErrorRecord <ErrorRecord[]>

If an error record should be noted with the message, add the full record here. Especially designed for use

with Warning-mode, it can legally be used in either mode. The error will be added to the $Error variable and

enqued in the logging/debugging system.



Required? false

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-Exception <Exception>

Allows specifying an inner exception as input object. This will be passed on to the logging and used for

messages. When specifying both ErrorRecord AND Exception, Exception wins, but ErrorRecord is still used for

record metadata.



Required? false

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-Once <String>

Setting this parameter will cause this function to write the message only once per session. The string passed

here and the calling function's name are used to create a unique ID, which is then used to register the action

in the configuration system. Thus will the lockout only be written if called once and not burden the system

unduly. This lockout will be written as a hidden value, to see it use Get-PSFConfig -Force.



Required? false

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-OverrideExceptionMessage [<SwitchParameter>]

Disables automatic appending of exception messages. Use in cases where you already have a speaking message

interpretation and do not need the original message.



Required? false

Position? named

Default value False

Accept pipeline input? False

Accept wildcard characters? false



-Target <Object>

Add the object the message is all about, in order to simplify debugging / troubleshooting. For example, when

calling this from a function targeting a remote computer, the computername could be specified here, allowing

all messages to easily be correlated to the object processed.



Required? false

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-EnableException <Boolean>

This parameters disables user-friendly warnings and enables the throwing of exceptions. This is less user

friendly, but allows catching exceptions in calling scripts.



Required? false

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-Breakpoint [<SwitchParameter>]

The breakpoint switch enables breaking on this debug message. By default, Write-PSFMessage will not interrupt

execution if the -Debug parameter is specified, even when writing to the debug stream.



Required? false

Position? named

Default value False

Accept pipeline input? False

Accept wildcard characters? false



-String <String>

The key to the localized message (omitting the module name). For more details on the PSFramework localization

feature, see the help on Import-PSFLocalizedString.



Required? true

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



-StringValues <Object[]>

The values to format into the localized string defined. For more details on the PSFramework localization

feature, see the help on Import-PSFLocalizedString.



Required? false

Position? named

Default value None

Accept pipeline input? False

Accept wildcard characters? false



<CommonParameters>

This cmdlet supports the common parameters: Verbose, Debug,

ErrorAction, ErrorVariable, WarningAction, WarningVariable,

OutBuffer, PipelineVariable, and OutVariable. For more information, see

about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).



INPUTS



OUTPUTS



NOTES









-------------- Example 1: Simple verbose message --------------



Write-PSFMessage -Message "Connecting to $computer"



Writes the message "Connecting to $computer" to verbose. Will also log the message.



_

----------------- Example 2: Writing a warning -----------------



Write-PSFMessage -Level Warning -Message "Failed to retrieve additional network adapter information from $computer"



Writes the message "Failed to retrieve additional network adapter information from $computer" as a warning. Will

also log the message.



_

------------ Example 3: Including extra information ------------



Write-PSFMessage -Level Verbose -Message "Connecting to $computer" -Target $computer



Writes the message "Connecting to $computer" to verbose. Includes the variable $computer in the message. This has

no effect on the text shown but will be available for debugging purposes. Will also log the message.



_

------------ Example 4: Writing a message once only ------------



Write-PSFMessage -Level Host -Message "This command has been deprecated, use 'Get-NewExample' instead" -Once

'Get-Example'



Writes the message "This command has been deprecated, use 'Get-NewExample' instead" to the screen. This message

will only be shown once per powershell process. Will also log the message.



_

--------------- Example 5: Passing on exceptions ---------------



Write-PSFMessage -Level Warning -Message "Failed to retrieve additional network adapter information from

$computer" -Target $computer -ErrorRecord $_



This example assumes to be executed within a catch block. Writes the message "Failed to retrieve additional

network adapter information from $computer" as a warning. Will also append the message of the exception to the

text. Will also add the error record to the error log Will also log the message.



-

------------- Example 6: Overriding Error Messages -------------



Write-PSFMessage -Level Warning -Message "Failed to change network adapter settings, this command requires

elevation. Restart your console as admin and try again" -Target $computer -ErrorRecord $_ -OverrideExceptionMessage



Similar to Example 5, this shows how to write an error message with debugging information attached. The key

difference here is that this assumes the error message has been properly interpreted for the end user, making it

no longer desirable to automatically append the exception message.



_

----------------- Example 7: Tagging messages -----------------



Write-PSFMessage -Message "Connecting to $computer" -Target $computer -Tag 'connect','CIM'



This shows how to use the -Tag parameter to add tags to a message. These can later be used with Get-PSFMessage or

the logs to filter messages by. Tags can also be used to apply rules to, such as where to log to.



_

--------- Example 8: Overriding debugging information ---------



Write-PSFMessage -Message "Connecting to $computer" -Line 21 -File "Connect-Computer.ps1"



The message system contains a lot of extra information that can be useful when debugging, such as file and line it

was written from. However depending on your build and import practices, those might not be a perfect fit for you.

Thus it is possible to override them, to aid with debugging your code.



_

------ Example 9: Explicitly specifying meta information ------



Write-PSFMessage -Message "Doing something" -FunctionName "Get-BeerParallel" -ModuleName "BeerFactory"



By default, Write-PSFMessage automatically gathers module and function information. However, this doesn't always

work, for example on scriptblocks that are run in separate runspaces. For those instances, you can manually

specify the command to display. Note: Logging is runspace-safe, so you can use this command parallel in multiple

runspaces. All messages from all runspaces are visible with Get-PSFMessage.



_

--------------- Example 10: Supporting Debugging ---------------



Write-PSFMessage -Level Debug -Message "Executing SQL Query 'SELECT * FROM table'" -Breakpoint



By using the breakpoint parameter in this message, PowerShell will break into the debugger at this position, if

the command writing this message is run with the -Debug parameter. By default, Write-PSFMessage will never

interrupt execution when -Debug is specified, in contrast to how Write-Debug acts.



RELATED LINKS

Online Documentation https://psframework.org/documentation/c ... ssage.html