2014 Winter PowerShell Scripting Games Wrap Up #4
Summary: Microsoft Scripting Guy, Ed Wilson, continues his Scripting Games 2014 wrap up with a discussion of error and verbose message streams.
Microsoft Scripting Guy, Ed Wilson, is here. Things are starting to settle down here in the scripting household. Windows PowerShell Saturday #007 was a rousing success in Charlotte, North Carolina. Valentine’s Day was cool and a special treat for the Scripting Wife and I, and the 2014 Winter Scripting Games have concluded. So what’s to do? Well, today I am sipping a nice cup of Charleston Breakfast tea. I added peppermint, spearmint, honey, fresh lemon, and a cinnamon stick to the mixture. It is quite refreshing. Charleston Breakfast tea is one of the teas that is grown at the Charleston Tea Plantation. It has a nice robust flavor when steeped for four minutes in 208 degree water.
Note This is the fourth in a series of blog posts in which I talk about things I noticed whilst grading submissions for the
2014 Winter Scripting Games. In case you missed the previous episodes:
- 2014 Winter PowerShell Scripting Games Wrap Up #1
Talked about best practices for using aliases and for formatting of Windows PowerShell scripts. - 2014 Winter PowerShell Scripting Games Wrap Up #2
Talked about the need for and the use of structured error handling. - 2014 Winter PowerShell Scripting Games Wrap Up #3
Talked about using standard Windows folders from within Windows PowerShell scripts.
In today’s post, I’ll talk about using the Write-Verbose and Write-Error streams in Windows PowerShell scripts.
Alternative output message streams
One of the things I saw while grading scripts for the 2014 Winter Scripting Games was people creating their own alternate message streams. For example, they might do something like the following:
If($verbose) {Write-Host "This is verbose output"}
ELSE {Write-Host "This is normal output"}
Although this sort of thing might actually work (at least to an extent), it is not optimal. In fact, it causes a lot of extra work. This is because Windows PowerShell already has several message streams including:
- Normal output
- Errors
- Warnings
- Verbose output
- Debug messages
Whether these messages display anything is due to the configuration of one of the following Preference variables:
- DebugPreference
- ErrorActionPreference
- VerbosePreference
- WarningPreference
The neat thing is that I implement my script in the proper Windows PowerShell fashion, then I can capture these alternate message streams in a text file via the redirection operators introduced in Windows PowerShell 3.0. The following table lists the redirection operators.
Note The 2>, 2>>, and 2&1 operators existed in Windows PowerShell 1.0.
Operator |
Description |
Example |
> |
Sends output to the specified file |
Get-Process > Process.txt |
>> |
Appends the output to the contents of the specified file |
dir *.ps1 >> Scripts.txt |
2> |
Sends errors to the specified file |
Get-Process none 2> Errors.txt |
2>> |
Appends errors to the contents of the specified file |
Get-Process none 2>> Save-Errors.txt |
2>&1 |
Sends errors (2) and success output (1) to the success output stream |
Get-Process none, Powershell 2>&1 |
3> |
Sends warnings to the specified file |
Write-Warning "Test!" 3> Warnings.txt |
3>> |
Appends warnings to the contents of the specified file |
Write-Warning "Test!" 3>> Save-Warnings.txt |
3>&1 |
Sends warnings (3) and success output (1) to the success output stream |
Function Test-Warning {Get-Process PowerShell; Write-Warning "Test!" } Test-Warning 3>&1 |
4> |
Sends verbose output to the specified file |
Import-Module * -Verbose 4> Verbose.txt |
4>> |
Appends verbose output to the contents of the specified file |
Import-Module * -Verbose 4>> Save-Verbose.txt |
4>&1 |
Sends verbose output (4) and success output (1) to the success output stream |
Import-Module * -Verbose 4>&1 |
5> |
Sends debug messages to the specified file |
Write-Debug "Starting" 5> Debug.txt |
5>> |
Appends debug messages to the contents of the specified file |
Write-Debug "Saving" 5>> Save-Debug.txt |
5>&1 |
Sends debug messages (5) and success output (1) to the success output stream |
Function Test-Debug { Get-Process PowerShell; Write-Debug "PS" } Test-Debug 5>&1 |
*> |
Sends all output types to the specified file |
Function Test-Output { Get-Process PowerShell, none; Write-Warning "Test!"; Write-Verbose "Test Verbose"; Write-Debug "test debug"} ; Test-Output *> Test-Output.txt |
*>> |
Appends all output types to the contents of the specified file |
Test-Output *>> Test-Output.txt |
*>&1 |
Sends all output types (*) to the success output stream |
Test-Output *>&1 |
An example of how to use the alternate message streams is shown here:
$desktopPath = [System.Environment]::GetFolderPath("Desktop")
Function Out-VerboseStream
{
BEGIN { $oldVerbosePreference = $VerbosePreference }
PROCESS {
$VerbosePreference = "Continue"
Write-Verbose "This is verbose output"
"This is regular output" }
END {$VerbosePreference = $oldVerbosePreference }
}
The key features are to set the preference variable to “Continue” to permit it to output. As a best practice, you should set it back when you are finished. As shown in the following image, I first run the function, and the verbose stream and the regular stream appear in the output pane.
I now use the redirection operator to redirect the verbose stream output to a text file:
Now when I use the redirection operator to redirect the verbose stream, it goes in a text file.
The following table illustrates the different type of redirection characters that are used to represent the message streams.
Character |
Meaning |
* |
All output |
1 |
Success output |
2 |
Errors |
3 |
Warning messages |
4 |
Verbose output |
5 |
Debug messages |
That is all there is to using different output streams. 2014 Winter PowerShell Scripting Games Wrap-Up Week continues tomorrow when I will talk about using the Switch statement.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy
0 comments