PowerShell v3 in a Year Day 14 Write Warning

Having written my share of large, complex scripts, I find Write-Warning to be a tremendously useful cmdlet. As noted in the help, "The Write-Warning cmdlet writes a warning message to the Windows PowerShell host. The response to the warning depends on the value of the users $WarningPreference variable and the use of the WarningAction common parameter." Although we have not covered the $WarningPreference variable yet, which can be found under Get-Help about_CommonParameters and about_Preference_Variables, we can quickly cover that by noting that the preference variable, $WarningPreference, is a PowerShell environmental variable used to control an entire sessions setting. As with other Preference variables you have four options:

1. Stop: Displays the warning message and an error message and then stops executing.
2. Inquire: Displays the warning message and then prompts for permission to continue.
3. Continue: Displays the warning message and then (Default) continues executing.
4. SilentlyContinue: Does not display the warning message. Continues executing.

As with other enumerations in PowerShell, there is corresponding set of strings and enum, integer values to connect the dots with. The actual .NET object type correlating with this enumeration is System.Management.Automation.ActionPreference. Below is the list of numeric values associated with the string enums (and how to get them):

• 0: 0 - SilentlyContinue
• 1: 1 - Stop
• 2: 2 - Continue
• 3: 3 - Inquire
• 4: 4 - Ignore

And, here is a 5 line command to generate the previous output:

0..4 |

ForEach-Object {

    $WarningPreference= $_;

    "$($_): $($WarningPreference.value__) - $($WarningPreference.ToString())"

}

Now the usefulness of this cmdlet really comes into play when you have to notify folks, "Hey, weve had a problem in the logic, but, its not big enough to stop the process. In short, perfect for logging to come back later and address. As a script writer, I know I have plenty of times I need to know about something and stopping the script is really not interest enough.

One of the nice features about Write-Warning is the default formatting when working in the console. It is very clear that, when you call Write-Warning, something is not right. As it outputs to the host you can see a distinct. In this example, below, I do a simple, single word, Test, to the -Message parameter. I stick, in my shell, to the defaults of blue background, with white text. In this case, PowerShell outputs this:

PS C:Userswsteele> Write-Warning -Message Test

WARNING: Test

As you can see, we get orange. I left the default formatting, as it appears in the shell, to demonstrate exactly how you will be dealing with Warning data.

Now, as my example shows, you can simply output Write-Warning directly to the host and it will work fine. However, there are scenarios where people unwittingly encounter these colors and dont quote know why. In my cases, Write-Warning is an explicitly called cmdlet, and, there are explicit reasons they are called, more often than not. So, lets look a little more closely at how that occurs and what we can do with it when it does in fact pop up.

Write-Warning has two parameters:

1. Message: Specifies the warning message.
2. Common Parameters: This cmdlet supports the common parameters: 
1. Verbose, 
2. Debug,
3. ErrorAction, 
4. ErrorVariable, 
5. WarningAction, 
6. WarningVariable,
7. OutBuffer
8. and OutVariable. 

For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).

Below are a few examples straight from the v3 help. The help illustrate standard use cases.

• This command displays the message "WARNING: This is only a test warning."

PS C:> write-warning "This is only a test warning."

• This example shows that you can use a pipeline operator (|) to send a string to Write-Warning. You can save the string in a variable, as shown in this command, or pipe the string directly to Write-Warning.

PS C:> $w = "This is only a test warning."PS C:>$w | write-warning

• This example shows the effect of the value of the $WarningPreference variable on a Write-Warning command. The first command displays the default value of the $WarningPreference variable, which is "Continue". As a result, when you write a warning, the warning message is displayed and execution continues. When you change the value of the $WarningPreference variable, the effect of the Write-Warning command changes again. A value of "SilentlyContinue" suppresses the warning. A value of "Stop" displays the warning and then stops execution of the command. For more information about the $WarningPreference variable, see about_Preference_Variables.

PS C:> $warningpreferenceContinuePS C:>write-warning "This is only a test warning."This is only a test warning.PS C:>$warningpreference = "SilentlyContinue"PS C:>write-warning "This is only a test warning."PS C:>PS C:>$warningpreference = "Stop"PS C:>write-warning "This is only a test warning."WARNING: This is only a test message.Write-Warning : Command execution stopped because the shell variable "WarningPreference" is set to Stop.At line:1 char:14+ write-warning <<<<  "This is only a test message."

• This example shows the effect of the WarningAction common parameter on a Write-Warning command. You can use the WarningAction common parameter with any cmdlet to determine how Windows PowerShell responds to warnings resulting from that command. The WarningAction common parameter overrides the value of the $WarningPreference only for that particular command. This command uses the Write-Warning cmdlet to display a warning. The WarningAction common parameter with a value of "Inquire" directs the system to prompt the user when the command displays a warning. For more information about the WarningAction common parameter, see about_CommonParameters.

PS C:> write-warning "This is only a test warning." -warningaction Inquire
WARNING: This is only a test warning.
Confirm
Continue with this operation?
[Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (default is "Y"): 

 In most cases, the reason I use the Warning is to indicate a failed tweak or modification. 

Related Post: