{"id":8621,"date":"2015-01-15T06:00:00","date_gmt":"2015-01-15T14:00:00","guid":{"rendered":"http:\/\/www.sapien.com\/blog\/?p=8621"},"modified":"2016-12-15T15:09:16","modified_gmt":"2016-12-15T23:09:16","slug":"manage-errors-in-a-gui-application","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2015\/01\/15\/manage-errors-in-a-gui-application\/","title":{"rendered":"Manage Errors in a GUI Application"},"content":{"rendered":"

Follow @juneb_get_help<\/a><\/p>\n

In a previous post<\/a>, I talked about displaying output in a GUI application. But I really covered only the primary output of cmdlets. In this post, we’ll discuss some very basic strategies for detecting and displaying terminating and non-terminating errors in a GUI application.<\/p>\n

This is a critical topic. If you’re used to scripting in the console, errors are displayed automatically. But, in a GUI program, you manage the output — all of it. And nothing appears in your application window unless you place it there explicitly.<\/p>\n

Your application’s response to an error can be as varied as your imagination — from a simple “Error” message box to changing the entire form, changing colors, and popping up help messages. But, in this post, we’ll show you the basics.<\/p>\n

 <\/p>\n

Errors Do Not Appear Automatically<\/h2>\n

In the Windows PowerShell console, both terminating and non-terminating errors appear in the all-too-familiar red text.<\/p>\n

PS C:\\ps-test> 1\/0\r\nAttempted to divide by zero.\r\nAt line:1 char:1\r\n+ 1\/0\r\n+ ~~~\r\n+ CategoryInfo : NotSpecified: (:) [], RuntimeException\r\n+ FullyQualifiedErrorId : RuntimeException<\/span><\/pre>\n
In PowerShell Studio, when you run a command that generates an error …<\/p>\n
$buttonStart_Click = {\r\n    $textboxOutput.Text = 1\/0\r\n}<\/pre>\n
… the error appears in the Output pane.<\/p>\n
\"image\"<\/a><\/p>\n
 <\/p>\n
But, when you package the .psf file into an executable file (.exe) and run it, NOTHING<\/b> appears in the GUI window. There is no standard output to display. And, this code doesn’t capture or redirect the error output to any control in the UI.<\/p>\n
\"clip_image003\"<\/a><\/p>\n
 <\/p>\n
This result is confusing to users who are expecting feedback from the action of clicking the button.<\/p>\n
Let’s fix this.<\/p>\n
 <\/p>\n
Errors do not stop a GUI application<\/h2>\n
Windows PowerShell supports two distinct types of errors. Terminating errors<\/i> stop the pipeline. Non-terminating<\/i> errors let the pipeline continue.<\/p>\n
But neither terminating nor non-terminating errors stop a GUI application. The application continues to run. You can respond to any error by closing the application, but to do so, you must explicitly close the form. It doesn’t happen automatically.<\/p>\n
Similarly, you can also respond to any error, including a terminating error, by reinitializing your input controls and letting the user try again. The choice is yours, but you need to consider the options and implement your response.<\/p>\n
 <\/p>\n
Display errors in the output window<\/h2>\n
The simplest way to notify a user of an error is to display an error in the text box that is designed for standard output.<\/p>\n
This example uses a Try-Catch<\/b><\/a> block to catch terminating errors in a Get-Command<\/b><\/a> command. This sample code displays an error message when the user types an empty string.<\/p>\n
$buttonGetCommand_Click = {\r\n    try\r\n    {\r\n        $cmdlet = textboxInput.Text\r\n        $textboxOutput.Text = Get-Command -Name $cmdlet | \r\n            Format-Table -AutoSize | \r\n            Out-String\r\n    }\r\n    catch\r\n    {\r\n        $textboxOutput.Text = \"Enter a cmdlet name. `\r\n            The name cannot be an empty string.\"\r\n    }\r\n}<\/pre>\n
Here is the result.<\/p>\n
\"clip_image004\"<\/a><\/p>\n
Be sure to fix the code to avoid obvious terminating errors, like this $null value error, but include a Try-Catch<\/b> block (preferred) or Trap<\/b> statement (outdated, but still available) to handle the ones that you didn’t anticipate.<\/p>\n
 <\/p>\n
Display errors in red text<\/h2>\n
When you use the same output control for standard and error output, be sure to make errors immediately recognizable by displaying them in red text. Use the ForeColor<\/b> property of a Textbox<\/b> with a value of ‘Red’.<\/p>\n
When the output is read-only, use a RichTextBox<\/b> control, instead of a TextBox<\/b>. When you set the ReadOnly<\/b> property of a Textbox<\/b> to $true, the ForeColor<\/b> property is overridden by ReadOnly<\/b> default colors. The RichTextBox<\/b> control implements the ForeColor<\/b> property value even when ReadOnly<\/b> is $true.<\/p>\n
This sample code displays the contents of a file. The user types the path and file name in the input text box ($textboxInput) and the script displays the file content in a rich text box ($richTextBoxOutput).<\/p>\n
$buttonGetContent_Click = {\r\n    $this.Enabled = $false\r\n    try\r\n    {\r\n        if (!($file = $textboxInput.Text.Trim()))\r\n        {\r\n            Display-Error \"File name cannot be blank. Enter a path and file name.\"\r\n        }\r\n        else if (!(Resolve-Path $file))\r\n        {\r\n            Display-Error `\r\n                -ErrorString \"Can't find $($Error[0].CategoryInfo.TargetName). `\r\n                Check the path and file name and try again.\"\r\n        }\r\n        elseif (!($richtextboxOutput.Text = `\r\n            Get-Content -Path $file -ErrorVariable fileErr | \r\n            Out-String))\r\n        {\r\n            Display-Error -ErrorString \"Can't get content of $($file). `\r\n                `nError is: $($fileErr).\"\r\n        }\r\n    }\r\n    catch\r\n    {\r\n        Display-Error -ErrorString \"Unforeseen error. Please try again. `\r\n            `nIf the problem recurs, contact juneb@sapien.com.\"\r\n    }\r\n}<\/pre>\n
 <\/p>\n
The code assigns the standard output to the Text<\/b> method of the rich text box. To display each value on a separate line, use the Raw<\/b> parameter of the Get-Content<\/a> <\/b>cmdlet, which returns a single string, instead of an array, or the Out-String<\/a><\/b> cmdlet, which converts the output to a single string.<\/p>\n
$richtextboxOutput.Text = Get-Content -Path $file -ErrorVariable fileErr -Raw<\/pre>\n
-or-<\/p>\n
$richtextboxOutput.Text = Get-Content -Path $file -ErrorVariable fileErr | Out-String<\/pre>\n
 <\/p>\n
Here’s the standard output:<\/p>\n
\"clip_image005\"<\/a><\/p>\n
 <\/p>\n
To display any error, the script calls the Display-Error<\/b> function, which sets the ForeColor<\/b> property of the rich text box to red, assigns the error message to the rich text box’s Text<\/b> property, and places the cursor in the input text box, which signals the user to try again.<\/p>\n
function Display-Error\r\n{\r\n    param\r\n    (\r\n        [parameter(Mandatory = $true)]\r\n        [String]\r\n        $ErrorString\r\n    )\r\n    \r\n    $richtextboxOutput.ForeColor = 'Red'\r\n    $richtextboxOutput.Text = $ErrorString\r\n    $textboxInput.Focus()\r\n}<\/pre>\n
Here’s the result.<\/p>\n
\"clip_image006\"<\/a><\/p>\n
 <\/p>\n
Unfortunately, if you try to restore the ForeColor<\/b> in the same function, it’s restored immediately and you never see the red text. I could have used the SelectionColor property, but, instead, I restored the standard text color in the TextChanged<\/b> event of the input text box.<\/p>\n
So, when the user tries again, the output is cleared, the button is re-enabled, and the original text color is restored.<\/p>\n
$textboxInput_TextChanged={\r\n    $richtextboxOutput.Clear()\r\n\r\n    if ($textboxInput.Text.Trim() -ne \"\")\r\n    {\r\n        $buttonGetContent.Enabled = $true\r\n        $richtextboxOutput.ForeColor = 'WindowText'\r\n    }\r\n}<\/pre>\n
 <\/p>\n
Display raw errors<\/h2>\n
Displaying the error message that Windows PowerShell returns is considered to be bad practice. The error messages in a well-designed application should be clear, well-written, and customized for the controls in the interface.<\/p>\n
\"clip_image007\"<\/a><\/p>\n
 <\/p>\n
However, you might want to include some elements of the raw error message in your error message display.<\/p>\n
For example, the error message in this code includes the fully-qualified path that the cmdlet actually searched ($error[0].CategoryInfo.TargetName). This is really important when the user enters a file name without a path and misjudges the current directory. It’s so useful that I substitute Resolve-Path<\/a>, which returns this error, for the more traditional Test-Path<\/a>, which returns a Boolean value ($True\/$False).<\/p>\n
To display the error message to the user, the code assigns the error message to the value of the Text<\/b> property of the RichTextBox<\/b>.<\/p>\n
if (!(Resolve-Path $file))\r\n{\r\n    $richtextbox.ForeColor = 'Red'\r\n    $textboxInput.Focus()\r\n    $richtextboxOutput.Text = \"Can't find $($Error[0].CategoryInfo.TargetName). `\r\n        Check the path and file name and try again.\"\r\n}<\/pre>\n
Here’s the result.<\/p>\n
\"clip_image008\"<\/a><\/p>\n
 <\/p>\n
Display errors in an error window<\/h2>\n
You can also display errors in an error window. This occupies a lot of real estate, but might occasionally be a useful element.<\/p>\n
This code assigns standard output to the Text method of $richtextBoxOutput, as in the previous example.<\/p>\n
$richtextboxOutput.Text = Get-Content -Path $file -ErrorVariable fileErr | Out-String<\/pre>\n
But, it assigns errors to the Text method of $richtextBoxError.<\/p>\n
if (!($file = $textboxInput.Text.Trim())\r\n{\r\n    $richtextboxError.Text = \"File name cannot be blank. Enter a path and file name.\"\r\n}<\/pre>\n
Because the $richtextboxError is a dedicated error display, you can set its ForeColor<\/b> property to ‘Red’ in the Properties dialog and never change it, sot here’s no need for a separate DisplayError function.
\nHere’s the result when the command succeeds.<\/p>\n
\"clip_image009\"<\/a><\/p>\n
 <\/p>\n
And here’s the result when it fails.<\/p>\n
\"clip_image010\"<\/a><\/p>\n
 <\/p>\n
You might be tempted to make the error box invisible until you use it ($richtextboxError.Visible=$false), but invisible text boxes still occupy space. And the result is, um, disconcerting. Don’t do it.<\/p>\n
\"clip_image011\"<\/a><\/p>\n
 <\/p>\n
Display errors in a message box<\/h2>\n
For detailed help with message box variations, see Spotlight on the MessageBox Control.<\/em><\/p>\n
You can also display errors in a message box. This is quick and easier than maintaining a separate text box.<\/p>\n
A message box isn’t a control. You create it on the fly and, by default, it includes an OK button. You don’t need to create it before you use it and it disappears automatically when the user clicks OK.<\/p>\n
For example, if the Resolve-Path<\/a> cmdlet can’t find the specified file, a message box pops up with the error message. Then,\u00a0the code sets the focus back to the input text box.<\/p>\n
\"clip_image012\"<\/a><\/p>\n
 <\/p>\n
To create a basic message box in PowerShell Studio, type msgbox<\/b> and then press TAB. The msgbox<\/b> snippet calls the static Show method with strings for the text and caption.<\/p>\n
[void][System.Windows.Forms.MessageBox]::Show(\"Text\",\"Caption\")<\/pre>\n
If you want something fancier, you can use the variety of overloads for the Show<\/a> method.<\/p>\n
Here’s the condition that creates and opens a message box when the Resolve-Path command fails. After displaying the message box, I call the Focus<\/b> method of the input text box, which places the cursor in the input box, showing the user how to try again.<\/p>\n
elseif (!(Resolve-Path $file))\r\n{\r\n    $errorMsg = \"Can't find $($Error[0].CategoryInfo.TargetName). `\r\n        Check the path and file name and try again.\"\r\n    $caption = \"Path error\"\r\n    [System.Windows.Forms.MessageBox]::Show($errorMsg, $caption)\r\n}<\/pre>\n
 <\/p>\n
Use an Error Provider<\/h2>\n
An ErrorProvider<\/a> control (see PowerShell Studio-specific info<\/a>) displays a little icon beside an input field. By default, the icon blinks every 250 milliseconds and when you hover over the icon, it displays a tool tip.<\/p>\n
You can use the error provider to indicate an error on a form.<\/p>\n
\"clip_image013\"<\/a><\/p>\n
 <\/p>\n
To add an error provider control to your form, in the PowerShell Studio Toolbox, double-click ErrorProvider<\/b>. You do not need to position the ErrorProvider<\/b> near the input box. You use code to associate it.<\/p>\n
To activate the error provider, use its SetError<\/b> method. The first argument is the control that you want to associate with the error provider; the second argument is the text of the tool tip.<\/p>\n
For example, in this code, errorprovider1<\/b> appears beside $textboxInput<\/b> when running the Test-Path<\/a> cmdlet on the value in the text box fails.<\/p>\n
elseif (!(Test-Path $file))\r\n{\r\n    $errorprovider1.SetError($textboxInput, \"File not found. Try again.\")\r\n}<\/pre>\n
 <\/p>\n
Write Useful Error Messages<\/h2>\n
I’ve reviewed a few simple ways to display errors in a GUI application. These are essential, because errors don’t appear automatically.<\/p>\n
But the best thing that you can do for users is beyond the scope of this post — and that is to write clear error messages that explain the problem, how to fix it, and how to prevent it.<\/p>\n
June Blender is a technology evangelist at SAPIEN Technologies, Inc. You can reach her at <\/em>juneb@sapien.com<\/em><\/a> or follow her on Twitter at <\/em>@juneb_get_help<\/em><\/a>.<\/em><\/p>\n","protected":false},"excerpt":{"rendered":"
Follow @juneb_get_help In a previous post, I talked about displaying output in a GUI application. But I really covered only the primary output of cmdlets. In this post, we’ll discuss some very basic strategies for detecting and displaying terminating and non-terminating errors in a GUI application. This is a critical topic. If you’re used to […]<\/p>\n","protected":false},"author":31,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[932,703],"tags":[934,1016],"class_list":["post-8621","post","type-post","status-publish","format-standard","hentry","category-beginners","category-powershell-studio","tag-juneb","tag-powershell-studio"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/8621","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/users\/31"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/comments?post=8621"}],"version-history":[{"count":26,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/8621\/revisions"}],"predecessor-version":[{"id":12894,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/8621\/revisions\/12894"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=8621"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=8621"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=8621"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}