Powershell error view

By now, I am sure you’ve heard the news: PowerShell 7 is no longer a beta product and the latest release has reached GA (generally available) status. In short, this means that Microsoft now considers PowerShell7 production ready! From this point forward you should begin to use PowerShell7 as your daily driver for all things PowerShell. Today I’d like to show you one aspect of PowerShell that is greatly improved: Error Handling and Error Messages.

Error Views

Before I can jump into the new features; let’s review what’s was already available in PowerShell prior to the v7 release. Let’s run some code and generate an error.

[int]$number = Read-Host "What is the latest version of PowerShell ?"

In the above code, I am prompting the user to answer a question and saving the answer to a variable called $number. I am expecting the answer to be a number so I cast the variable as an INT, meaning that the variable will only accept numbers as being valid. Anything else will return an error.

When I run the code I get prompted to answer the question. For our purposes, I will input a letter instead of a number causing an error to be thrown. The error returned contains a bunch of information, but notice it has a standard format you have probably seen many times prior.

The layout of this message is called the «normal view». This layout should look pretty familiar; it’s the default error view in PowerShell 5 and earlier. However, there is another way this error could have been displayed.

Let’s re-run the code again, but this time set a view called «CategoryView» for a variable called $errorview and see what happens.

$errorview = "categoryview"
[int]$number = Read-Host "what is the latest version of PowerShell ?"

In our example above, running the same code with this other error view produces a different error message. This view is called the Category View and it can be set manually to override the normal view which we saw in the previous example.

Here’s a better example of the category view showing an error that describes the problem.

$errorview = "categoryview"
test-connection -ComputerName "notrealcomputer" -count 1

So what does this have to do with PowerShell 7?

PowerShell 7 contains the same two views but now includes a third view called concise view. The same code in PowerShell 7 produces a short but useful error message.

One of the first things you will notice using PowerShell 7 is that error messages are much improved and more succinct. This error message for Test-Connection is short but adequetly describes the issue.

In this code sample, I have purposely misspelled the Select-Object cmdlet. Again we see that the message clearly states the problem.

«Conciseview» is the default view in PowerShell. Nothing needs to be configured to get these shorter, cleaer messages. All errors produced will be easier to understand and point more directly to what caused the error in your code. If you prefer one of the other views, you can switch at anytime by updating the value of $Errorview and then PowerShell will produce errors similar to the message you have seen in previous versions.

Get-Error

PowerShell 7 also includes a new cmdlet named Get-Error. The cmdlet retrieves and displays extended error information for recent error messages from the current PowerShell session. Extended error information is ALL the error information that is recorded when an error is thrown. The views I discussed earlier are only presenting a subset of the error data available.

In the screencap below, I generate an error by calling an invalid CIM namespace. Afterwards, I then run Get-Error to see the extended information available for that error. You’ll notice that there is quite a bit of information available in additon to the original error message that was displayed at the first error.

Get-error not only displays extended error information on the most recent error message, it also can display all the errors that occurred in a session.

In my current sessionI have generated quite a few errors that are still in memory. I can use Get-Error to get the entire list and then retrieve the information as needed. For this example, I am going to use Out-Gridview to illustrate how many errors I have in memory.

Get-Error -newest 20 | Out-Gridview

All the information from past errors can be recalled and reviewed as long as the session is not cleared. That information can be useful when trying to pinpoint errors.

These new views and cmdlets provide more useful data when errors occur and more ways to go back and look at past errors. We also can dive in deep and look at the extended data for an extra deep view of what happened when an error occurred.
These new tools are just a scratch of the surface of the new features avalaible in PowerShell 7!

PowerShell 7 Blog Week

This post is part of the #PS7Now PowerShell Blog Week celebrating the general availability launch of PowerShell 7.

All week long look for the #PS7Now hashtag on Twitter for more great content or checkout the table below for direct links to authors who are participating in the #PS7Now PowerShell Blog Week.

These authors will be publishing content all week highlighting the new features available in PowerShell 7. Make sure you stop by their blogs or follow them on social media to keep up on all the latest PowerShell 7 posts!

$Errorview variable determines the display format of the error message in PowerShell. Before PowerShell 7 there were mainly two views,

• Normal View (Default view)

• Category View

With PowerShell version 7, one new additional error view category is included and now there are 3 $ErrorView categories for version 7.

• Concise View (Default)

• Normal View

• Category View

We will understand each view one by one.

A ) Normal View

It is the default view before PowerShell version 7 and it produces the detailed multiline errors and bit noisy. It includes the exception name, category, line number of the error, etc.

$ErrorView = 'NormalView'
Get-ChildItem C:NoDirectory

Output

Get-ChildItem : Cannot find path 'C:NoDirectory' because it does not exist.
At line:1 char:1
+ Get-ChildItem C:NoDirectory
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : ObjectNotFound: (C:NoDirectory:String) [Get-ChildItem],
ItemNotFoundException
+ FullyQualifiedErrorId :
PathNotFound,Microsoft.PowerShell.Commands.GetChildItemCommand

B) Category View

Single liner and structured view, designed for the production environment. Its format is as below.

{Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

For example

$ErrorView = 'CategoryView'
Get-ChildItem C:NoDirectory

Output

ObjectNotFound: (C:NoDirectory:String) [Get-ChildItem], ItemNotFoundException

C) Concise View

The default view in PowerShell version 7. It provides a concise error message. If the error is from thecommand line it’s a single line error message.

For example

$ErrorView = 'ConciseView'
Get-ChildItem C:NoDirectory

Output

Get-ChildItem: Cannot find path 'C:NoDirectory' because it does not exist.

If the error is from the script then it is a multiline error message that contains the error message and the line number for the error.

$ErrorView = 'ConciseView'
PS C:> C:TempTestPS1.ps1

Output

Error message in Concise view
Get-ChildItem: C:TempTestPS1.ps1:2
Line |
2 | Get-ChildItem c:
onDirectory
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
| Cannot find path 'C:
onDirectory' because it does not exist.

The best way in my opinion to trap errors in PowerShell would be to use the following:

$Error[0].Exception.GetType().FullName

Here is an example of how to use this properly. Basically test what you are trying to do in PowerShell with different scenarios in which your script will fail.

Here is a typical PowerShell error message:

PS C:> Stop-Process -Name 'FakeProcess'
Stop-Process : Cannot find a process with the name "FakeProcess". Verify the process name and call the cmdlet again.
At line:1 char:1
+ Stop-Process -Name 'FakeProcess'
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (FakeProcess:String) [Stop-Process], ProcessCommandException
    + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShell.Commands.StopProcessCommand

Next you would get the exception of the error message:

PS C:> $Error[0].Exception.GetType().FullName
Microsoft.PowerShell.Commands.ProcessCommandException

You would setup your code to catch the error message as follows:

Try
{
    #-ErrorAction Stop is needed to go to catch statement on error
    Get-Process -Name 'FakeProcess' -ErrorAction Stop
}
Catch [Microsoft.PowerShell.Commands.ProcessCommandException]
{
    Write-Host "ERROR: Process Does Not Exist. Please Check Process Name"
}

Output would look like the following instead of the Powershell standard error in above example:

ERROR: Process Does Not Exist. Please Check Process Name

Lastly, you can also use multiple catch blocks to handle multiple errors in your code. You can also include a «blanket» catch block to catch all errors you haven’t handled. Example:

Try
{
    Get-Process -Name 'FakeProcess' -ErrorAction Stop
}

Catch [Microsoft.PowerShell.Commands.ProcessCommandException]
{
    Write-Host "ERROR: Process Does Not Exist. Please Check Process Name"
}

Catch [System.Exception]
{
    Write-Host "ERROR: Some Error Message Here!"
}

Catch
{
    Write-Host "ERROR: I am a blanket catch to handle all unspecified errors you aren't handling yet!"
}

Error Handling is a very important concept in every programming language including PowerShell which gives us several possibilities to manage errors in code.

In this article, I will try to cover as many as possible error handling concepts with examples from my practice and one of the important concepts is writing errors in external Error Log text file.

Why Should We Bother Handling Errors In PowerShell

It is no fun to run any code or application full of errors and bugs as the matter a fact it is quite annoying so in order for users to have a pleasant experience handling the errors is one of the essentials in programming.

PowerShell is no exception to that way of thinking and programming ethics although it can take some additional coding and effort but trust me it is always worth it.

I would be more than happy to share my experience with error handling and even more satisfied if I can hear your tips from the field so we can all enrich our knowledge on this very important subject.

Here is a general approach to error handling and logging errors into the external text file. I have an example in the next subheading that further explain each step so everything is much more understandable.

1. Identify which Commands need Error Handling in your Function, CmdLet or Script.
2. Set the ErrorAction parameter to value Stop for the command that needs Error Handling. This will stop executing the command when an error occurs and it will show the error message. Basically, we are making non-terminating errors into terminating in order to be able to handle the error in the catch block.
3. Command that has ErrorAction parameter set to value Stop is wrapped in Try { } block. So when Error occurs handling of the code will jump from the Try block to Catch block.
4. In Catch { } block that immediately follows after Try {} block, the error is handled by writing to the error log file on the disk.
5. We use our own Write-ErrorLog CmdLet inside Catch{ } block to write the error in a text file on the disk. (See the explanation and code here)
6. We have an additional switch error parameter to decide whether we want to write an error in the log file or not. This is totally optional.
7. Use the Finally { } block if needed.
8. Test the whole setup by intentionally breaking the code while in the development phase.
9. Since some of the CmdLets calls are Scheduled we have routine to check external Error Log text file at least once a week and investigate errors that are caught. This step is part of improving the overall quality of the written code.

Example Of PowerShell Error Handling

To show you Error Handling and implement previously defined steps I will use my own Get-CPUInfo CmdLet which is in the Common module of the Efficiency Booster PowerShell Project. Efficiency Booster PowerShell Project is a library of CmdLets that help us IT experts in day to day IT tasks.

In order to follow me along, I highly encourage you to download the zip file with the source code used in this example.

Here is the location of Get-CPUInfo script:
…[My] DocumentsWindowsPowerShellModules3common

Let’s use steps defined in the previous subheading to this example.

Step 1. I have identified the command that needs Error Handling in Get-CPUInfo CmdLet and that is a call to Get-CimInstance CmdLet.

Get-CimInstance @params 

Step 2. So I have set up the ErrorAction parameter to the value ‘Stop‘ for Get-CimInstance CmdLet in order to force non-terminating errors into terminating and then to be able to handle such errors.

INFO: I use parameter splatting when running CmdLet. If you want to know more about parameter splating please read this article.

            $params = @{ 'ComputerName'=$computer;
                         'Class'='Win32_Processor';
                         'ErrorAction'='Stop'}
            $CPUInfos = Get-CimInstance @params | 
                            Select-Object   @{label="ServerName"; Expression={$_.SystemName}}, 
                                            @{label="CPU"; Expression={$_.Name}}, 
                                            @{label="CPUid"; Expression={$_.DeviceID}}, 
                                            NumberOfCores, 
                                            AddressWidth

Step 3. Wrap up the call to Get-CimInstance CmdLet into the Try Block in order to be able to handle the error in a catch block that follows.

         try {
            Write-Verbose "Start processing: $computer - $env - $logicalname"
            Write-Verbose "Start Win32_Processor processing..."
            $CPUInfos = $null
            $params = @{ 'ComputerName'=$computer;
                         'Class'='Win32_Processor';
                         'ErrorAction'='Stop'}
            $CPUInfos = Get-CimInstance @params | 
                            Select-Object   @{label="ServerName"; Expression={$_.SystemName}}, 
                                            @{label="CPU"; Expression={$_.Name}}, 
                                            @{label="CPUid"; Expression={$_.DeviceID}}, 
                                            NumberOfCores, 
                                            AddressWidth           
            Write-Verbose "Finish Win32_Processor processing..."                    
            foreach ($CPUInfo in $CPUInfos) {
                Write-Verbose "Start processing CPU: $CPUInfo"
                $properties = @{ 'Environment'=$env;
                                 'Logical name'=$logicalname;
                                 'Server name'=$CPUInfo.ServerName;
            	                 'CPU'=$CPUInfo.CPU;
            	                 'CPU ID'=$CPUInfo.CPUid;
            	                 'Number of CPU cores'=$CPUInfo.NumberOfCores; 
                                 '64 or 32 bits'=$CPUInfo.AddressWidth;
                                 'IP'=$ip;
                                 'Collected'=(Get-Date -UFormat %Y.%m.%d' '%H:%M:%S)}
                $obj = New-Object -TypeName PSObject -Property $properties
                $obj.PSObject.TypeNames.Insert(0,'Report.CPUInfo')
                Write-Output $obj
                Write-Verbose "Finish processing CPU: $CPUInfo"
            }
 Write-Verbose "Finish processing: $computer - $env - $logicalname"                       
        }

Step 4. When the error occurs in the try block it is handled in the Catch Block.
It is important to notice following in the catch block of code:

• Get-CPUInfo CmdLet switch parameter $errorlog has been used to decide whether to log the errors in an external text file or not. This is completely optional.
• Certain Error properties are collected using an automatic variable $_ ($PSItem is another name for the same variable). If you want to know more about which properties we collect please read here.
• Collected data about the error that will be handled has been passed to another CmdLet Write-ErrorLog that will write the data in an external text log file. Please read here about Write-ErrorLog CmdLet.

catch {
            Write-Warning "Computer failed: $computer - $env - $logicalname CPU failed: $CPUInfos"
            Write-Warning "Error message: $_"
            if ( $errorlog ) {
                $errormsg = $_.ToString()
                $exception = $_.Exception
                $stacktrace = $_.ScriptStackTrace
                $failingline = $_.InvocationInfo.Line
                $positionmsg = $_.InvocationInfo.PositionMessage
                $pscommandpath = $_.InvocationInfo.PSCommandPath
                $failinglinenumber = $_.InvocationInfo.ScriptLineNumber
                $scriptname = $_.InvocationInfo.ScriptName
                Write-Verbose "Start writing to Error log."
                Write-ErrorLog -hostname $computer -env $env -logicalname $logicalname -errormsg $errormsg -exception $exception -scriptname $scriptname -failinglinenumber $failinglinenumber -failingline $failingline -pscommandpath $pscommandpath -positionmsg $pscommandpath -stacktrace $stacktrace
                Write-Verbose "Finish writing to Error log."
            }
        }

Step 5. I have already mentioned that Write-ErrorLog CmdLet has been used to write the error data into an external text log file. Read more about this CmdLet here.

Step 6. I did not need Finally { } block for this example.

Step 7. In the development phase, I was intentionally breaking Get-CPUInfo CmdLet to test my error handling code.

Step 8. If Get-CPUInfo CmdLet is part of the scheduled code I would look regularly Error log file and work on correcting all the bugs in the code produced by Get-CPUInfo CmdLet.

Chain Of Events When PowerShell Error Occurs

Let’s talk a little bit about what is happening when an error occurs in PowerShell and which events are triggered one after another.

• Call to CmdLet is failing and error has just occurred.
• Since we have ErrorAction parameter set to value Stop our non-terminating error has forced into terminating error so the execution of code stops.
• The error that is failing in the CmdLet is written in the $Error automatic variable by the PowerShell.
• We have forced the error to be terminating in order to be able to handle with try catch finally block of error handling.
• Since our CmdLet call is wrapped in Try block and error is terminating PowerShell can trigger error handling looking for a Catch block.
• We can have several Catch blocks for one try block. If we have a Catch block that handles the actual error number that block is executed.
• Otherwise, PowerShell will look Catch block that handles all error numbers.
• Optionally in the Catch block, we can have code that will write the error in the external text Error log file.
• We can use the automatic variable $Error or $_ object to read Error data and write them in the external file.
• If there is no Catch block PowerShell will look for Catch block in parent call if we have nested calls.
• If there are no further Catch block or no Catch block at all that will handle error then PowerShell looks for Finally block to execute which is used to clean up resources as needed.
• After executing Finally block error message will be sent to the error stream for further processing.

In further sections of this article, you can read in more detail about the many terms mentioned (ErrorAction, $Error, Try Catch Finally, Terminating, Non-Terminating, etc ) in this bulleted list in order to better understand them.

How To Write PowerShell Errors Into The External Log File

Here I will explain the code of Write-ErrorLog CmdLet that writes error data that occurs in CmdLets and handle the error data into an external text file.

Error data are written in the file named Error_Log.txt in folder PSlogs.

Write-ErrorLog CmdLet is part of the Efficiency Booster PowerShell Project and if you want to download the source code of this CmdLet please click here.

Here is the location of Write-ErrorLog script which is part of the Utils module:
…[My] DocumentsWindowsPowerShellModules2utils

Write-ErrorLog CmdLet Code

Here is the code of the whole Write-ErrorLog CmdLet.

<#
.SYNOPSIS
Writes errors that occur in powershell scripts into error log file.
.DESCRIPTION
Writes errors that occur in powershell scripts into error log file.
Error log file and error log folder will be created if doesn't exist.
Error log file name is Error_Log.txt and it has been saved into ..DocumentsPSlogs

.PARAMETER hostname
Name of the computer that is failing.

.PARAMETER env
Environment where computer is located. For example: Production, Acceptance, Test, Course etc.

.PARAMETER logicalname
Type of the server that is failing. For example: Application, Web, Integration, FTP, Scan, etc. 

.PARAMETER errormsg
Error message.

.PARAMETER exception
Error number.

.PARAMETER scriptname
Name of the powershell script that is failing.

.PARAMETER failinglinenumber
Line number in the script that is failing.

.PARAMETER failingline
Content of failing line.

.PARAMETER pscommandpath
Path to the powershell command.

.PARAMETER positionmsg
Error message position.

.PARAMETER stacktrace
Stack trace of the error.

.EXAMPLE
Write-ErrorLog -hostname "Server1" -env "PROD" -logicalname "APP1" -errormsg "Error Message" -exception "HResult 0789343" -scriptname "Test.ps1" -failinglinenumber "25" -failingline "Get-Service" -pscommandpath "Command pathc." -positionmsg "Position message" -stacktrace "Stack trace" 

.EXAMPLE
Help Write-ErrorLog -Full

.LINK 
Out-File
#>
Function Write-ErrorLog {
[CmdletBinding()]
param (

    [Parameter(Mandatory=$false,
                HelpMessage="Error from computer.")] 
    [string]$hostname,

    [Parameter(Mandatory=$false,
                HelpMessage="Environment that failed. (Test, Production, Course, Acceptance...)")] 
    [string]$env,

    [Parameter(Mandatory=$false,
                HelpMessage="Type of server that failed. (Application, Web, Integration...)")] 
    [string]$logicalname,
    
    [Parameter(Mandatory=$false,
                HelpMessage="Error message.")] 
    [string]$errormsg,
    
    [Parameter( Mandatory=$false,
                HelpMessage="Exception.")]
    [string]$exception,
    
    [Parameter(Mandatory=$false, 
                HelpMessage="Name of the script that is failing.")]
    [string]$scriptname,
     
    [Parameter(Mandatory=$false,
                HelpMessage="Script fails at line number.")]
    [string]$failinglinenumber,

    [Parameter(Mandatory=$false,
                HelpMessage="Failing line looks like.")]
    [string]$failingline,
    
    [Parameter(Mandatory=$false,
                HelpMessage="Powershell command path.")]
    [string]$pscommandpath,    

    [Parameter(Mandatory=$false,
                HelpMessage="Position message.")]
    [string]$positionmsg, 

    [Parameter(Mandatory=$false,
                HelpMessage="Stack trace.")]
    [string]$stacktrace
)
BEGIN { 
        
        $errorlogfile = "$homeDocumentsPSlogsError_Log.txt"
        $errorlogfolder = "$homeDocumentsPSlogs"
        
        if  ( !( Test-Path -Path $errorlogfolder -PathType "Container" ) ) {
            
            Write-Verbose "Create error log folder in: $errorlogfolder"
            New-Item -Path $errorlogfolder -ItemType "Container" -ErrorAction Stop
        
            if ( !( Test-Path -Path $errorlogfile -PathType "Leaf" ) ) {
                Write-Verbose "Create error log file in folder $errorlogfolder with name Error_Log.txt"
                New-Item -Path $errorlogfile -ItemType "File" -ErrorAction Stop
            }
        }
}
PROCESS {  

            Write-Verbose "Start writing to Error log file. $errorlogfile"
            $timestamp = Get-Date 
            #IMPORTANT: Read just first value from collection not the whole collection.
            "   " | Out-File $errorlogfile -Append
            "************************************************************************************************************" | Out-File $errorlogfile -Append
            "Error happend at time: $timestamp on a computer: $hostname - $env - $logicalname" | Out-File $errorlogfile -Append
            "Error message: $errormsg" | Out-File $errorlogfile -Append
            "Error exception: $exception" | Out-File $errorlogfile -Append
            "Failing script: $scriptname" | Out-File $errorlogfile -Append
            "Failing at line number: $failinglinenumber" | Out-File $errorlogfile -Append
            "Failing at line: $failingline" | Out-File $errorlogfile -Append
            "Powershell command path: $pscommandpath" | Out-File $errorlogfile -Append
            "Position message: $positionmsg" | Out-File $errorlogfile -Append
            "Stack trace: $stacktrace" | Out-File $errorlogfile -Append
            "------------------------------------------------------------------------------------------------------------" | Out-File $errorlogfile -Append                   
            
            Write-Verbose "Finish writing to Error log file. $errorlogfile"
}        
END { 

}
}
#region Execution examples
#Write-ErrorLog -hostname "Server1" -env "PROD" -logicalname "APP1" -errormsg "Error Message" -exception "HResult 0789343" -scriptname "Test.ps1" -failinglinenumber "25" -failingline "Get-Service" -pscommandpath "Command pathc." -positionmsg "Position message" -stacktrace "Stack trace" -Verbose
#endregion

Write-ErrorLog CmdLet Explained

Let’s make our hand’s a little bit “dirty” and dive into PowerShell code.

In the BEGIN block we:

• Check if folder PSlogs exist in the (My) Documents folder of the current user.
  • If the PSlogs folder doesn’t exist then create the folder.
• Check if file Error_Log.txt exists in the folder PSlogs.
  • If Error_Log.txt doesn’t exist then create the file.
• Now we can move on to PROCESS block code.

BEGIN { 
        
        $errorlogfile = "$homeDocumentsPSlogsError_Log.txt"
        $errorlogfolder = "$homeDocumentsPSlogs"
        
        if  ( !( Test-Path -Path $errorlogfolder -PathType "Container" ) ) {
            
            Write-Verbose "Create error log folder in: $errorlogfolder"
            New-Item -Path $errorlogfolder -ItemType "Container" -ErrorAction Stop
        
            if ( !( Test-Path -Path $errorlogfile -PathType "Leaf" ) ) {
                Write-Verbose "Create error log file in folder $errorlogfolder with name Error_Log.txt"
                New-Item -Path $errorlogfile -ItemType "File" -ErrorAction Stop
            }
        }
}

In the PROCESS block:

• We format the line of text that we want to write into the log file.
• Then we pipe formatted text to Out-File CmdLet with the Append parameter to write that line of text in the file.
• We repeat the process of formatting the line of text and appending of that line to the Error log file.

PROCESS {  

            Write-Verbose "Start writing to Error log file. $errorlogfile"
            $timestamp = Get-Date 
            #IMPORTANT: Read just first value from collection not the whole collection.
            "   " | Out-File $errorlogfile -Append
            "************************************************************************************************************" | Out-File $errorlogfile -Append
            "Error happend at time: $timestamp on a computer: $hostname - $env - $logicalname" | Out-File $errorlogfile -Append
            "Error message: $errormsg" | Out-File $errorlogfile -Append
            "Error exception: $exception" | Out-File $errorlogfile -Append
            "Failing script: $scriptname" | Out-File $errorlogfile -Append
            "Failing at line number: $failinglinenumber" | Out-File $errorlogfile -Append
            "Failing at line: $failingline" | Out-File $errorlogfile -Append
            "Powershell command path: $pscommandpath" | Out-File $errorlogfile -Append
            "Position message: $positionmsg" | Out-File $errorlogfile -Append
            "Stack trace: $stacktrace" | Out-File $errorlogfile -Append
            "------------------------------------------------------------------------------------------------------------" | Out-File $errorlogfile -Append                   
            
            Write-Verbose "Finish writing to Error log file. $errorlogfile"
} 

$PSItem or $_

$PSItem contains the current object in the pipeline object and we use it to read Error properties in this case.

Just a quick explanation of each Error property from the $_ ($PSItem) automatic variable that we collect and write in Logfile:

• $_.ToString() – This is Error Message.
• $_.Exception – This is Error Exception.
• $_.InvocationInfo.ScriptName – This the PowerShell script name where Error occurred.
• $_.InvocationInfo.ScriptLineNumber – This is line number within the PowerShell script where Error occurred.
• $_.InvocationInfo.Line – This is the line of code within PowerShell script where Error occurred.
• $_.InvocationInfo.PSCommandPath – This is the path to the PowerShell script file on the disk.
• $_.InvocationInfo.PositionMessage – This is a formatted message indicating where the CmdLet appeared in the line.
• $_.ScriptStackTrace – This is the Trace of the Stack.

As you can see on the screenshot below we collect really useful information about the Error that we handle in the Logfile. The pieces of information are presented in very neatly fashion so we can immediately see:

• which error occurred,
• what were the message and exception,
• where the error occurred (script name, script location, line number and line of the code in the script)
• even the call stack is shown if needed.

Here are the final result and an example of one formatted error logged in Error_Log.txt file.

************************************************************************************************************
Error happend at time: 09/11/2019 18:20:41 on a computer: APP01 -  - 
Error message: The WinRM client cannot process the request. If the authentication scheme is different from Kerberos, or if the client computer is not joined to a domain, then HTTPS transport must be used or the destination machine must be added to the TrustedHosts configuration setting. Use winrm.cmd to configure TrustedHosts. Note that computers in the TrustedHosts list might not be authenticated. You can get more information about that by running the following command: winrm help config.
Error exception: Microsoft.Management.Infrastructure.CimException: The WinRM client cannot process the request. If the authentication scheme is different from Kerberos, or if the client computer is not joined to a domain, then HTTPS transport must be used or the destination machine must be added to the TrustedHosts configuration setting. Use winrm.cmd to configure TrustedHosts. Note that computers in the TrustedHosts list might not be authenticated. You can get more information about that by running the following command: winrm help config.
   at Microsoft.Management.Infrastructure.Internal.Operations.CimAsyncObserverProxyBase`1.ProcessNativeCallback(OperationCallbackProcessingContext callbackProcessingContext, T currentItem, Boolean moreResults, MiResult operationResult, String errorMessage, InstanceHandle errorDetailsHandle)
Failing script: C:UsersdekibDocumentsWindowsPowerShellModules3commonGetCPUInfo.ps1
Failing at line number: 214
Failing at line:             $CPUInfos = Get-CimInstance @params | 

Powershell command path: C:UsersdekibDocumentsWindowsPowerShellModules3commonGetCPUInfo.ps1
Position message: C:UsersdekibDocumentsWindowsPowerShellModules3commonGetCPUInfo.ps1
Stack trace: at Get-CPUInfo, C:UsersdekibDocumentsWindowsPowerShellModules3commonGetCPUInfo.ps1: line 214
at , : line 1
------------------------------------------------------------------------------------------------------------

TIP: If your scripts are scheduled in Task Manager the best practice is to have a routine of regularly checking the Error Log file and investigate the errors that occurred since the last check. I am doing this once a week.

Errors In PowerShell

There are two types of Errors in PowerShell:

• Terminating
• Non-Terminating

Terminating Errors

Here are the important features of Terminating errors:

• terminates execution of command or script
• triggers Catch block and can be error handled by the Catch block.

Examples are syntax errors, non-existent CmdLets, or other fatal errors

Non-Terminating Errors

Here are important features of Non-Terminating Error:

• A non-fatal error.
• Allows execution to continue despite the failure that just occurred.
• It doesn’t trigger the Catch block and cannot be Error Handled in the Catch block by default.

Examples are permission problems, file not found, etc.

How To Force Non-Terminating Errors Into Terminating

Use the ErrorAction parameter with value Stop to force non-terminating error into terminating as in the following example. The reason why we want to make non-termination error into terminating one is to be able to catch the error when occurs.

$AuthorizedUser = Get-Content .DocumentsWindowsPowerShellProfile.ps1 -ErrorAction Stop 

Basically, the workflow is as follows.

• When an error occurs,
• a non-terminating error has changed into terminating one since we have Stop value on ErrrorAction parameter,
• then since terminating error has occurred try block will send the error handling to catch block where error can be processed and
• optionally written to the external log,
• optionally error handling can continue in the final block.

NOTE: ErrorAction parameter overrides temporarily ErrorActionPreference variable while the call to CmdLet has been processed.

How To Treat All Errors As Terminating

We use the ErrorActionPreference variable to treat all errors as terminating by setting to the value Stop in the:

• script
• or session

Write the following line of code at the begging of the script to treat all errors as terminating.

$ErrorActionPreference = Stop

Type in Windows PowerShell Console the same command to setup terminating errors for the session.

ErrorAction Common Parameter

ErrorAction parameter belongs to the set of common parameters that we can use with any CmdLet. If we set CmdLetBinding on Advanced Functions than PowerShell automatically makes common parameters available for that command.

This is a parameter that I always use with CmdLets that need error handling since the ErrorAction Parameter determines how the CmdLet responds to a non-terminating error. It has several values that we will talk about in a minute but the value that I like to use is Stop and it is used to make non-terminating errors into terminating errors as written in previous sections.

The ErrorAction parameter overrides the value of the $ErrorActionPreference variable when applied to the specific command.

Here are valid values:

• Continue (Default)
  • This is the default setting. Display error then continues execution.
• Stop
  • Display error, and stop the execution.
• Inquire
  • Displays error message and the user is asked to continue with execution.
• SilentlyContinue
  • No error message is displayed and execution is continued. However, the error message is added to the $Error automatic variable.
• Ignore
  • The same as SilentlyContinue, No error message is displayed and execution is continued. However, Ignore does not add an error message to the $Error automatic variable.
• Suspend
  • This one is for workflows. A workflow job is suspended to investigate what happened, then the workflow can be resumed.

$ErrorActionPreference Preference Variable Explained

$ErrorActionPreference preference variable determines how Windows PowerShell responds to a non-terminating error (an error that does not stop the cmdlet processing) in a script, cmdlet or at the command line

If we want to override the value of the ErrorActionPreference preference variable for the specific command we use the ErrorAction common parameter as explained here.

The valid values for $ErrorActionPreference preference variable are:

• Continue (Default)
  • This is the default setting. Display error then continues execution.
• Stop
  • Display error message, and stop the execution.
• Inquire
  • Displays error message and the user is asked to continue with execution.
• SilentlyContinue
  • No error message is displayed and execution is continued. However, the error message is added to the $Error automatic variable.
• Suspend
  • This one is for workflows. A workflow job is suspended to investigate what happened, then the workflow can be resumed.

Error Handling With Try/Catch/Finally Blocks

Try, Catch, and Finally, blocks are used to handle terminating errors in the scripts, functions, and CmdLets. A non-terminating error does not trigger Try block and Windows PowerShell will not look for Catch block to handle the error. So we need to force a non-terminating error to become terminating error using ErrorAction parameter with value Stop whenever we call some CmdLet or Advanced function.

Try block is used as part of the code that PowerShell will monitor for errors. The workflow in the Try block is as follows:

• Try block is the section of code that will be monitored for errors by Windows PowerShell.
• When the error occurs within Try block the error is saved to $Error automatic variable first.
• Windows PowerShell searches for a Catch block to handle the error if the error is terminating. If the Catch block has not been found in current scope Windows PowerShell will search for catch block in parent scopes for nested calls.
• Then the Finally block is run if exists.
• If there is no Catch block than the error is not handled and the error is written to the error stream.

One Try block can have several Catch Blocks that will handle different error types.

Catch block usually handles the error.

The Finally block is optional and can be only one. Usually, it is used to clean up and free the resources.

The syntax for Try, Catch, and Finally block:

try { } 
catch [],[]
   { } 
catch { } 
finally { }

Getting Error Information With $Error Automatic Variable

$Error automatic variable is an array of error objects (both terminating and the non-terminating) that occurred in the current PowerShell session. The most recent error that occurred is written with index 0 in the array as $Error[0]. If we have just opened the Windows PowerShell session the $Error variable is an empty array and ready to be used.

Check the number of Errors in $Error variable with the following code:

$Error.Count

To prevent the error from being written in $Error automatic variable set ErrorAction parameter to value Ignore.

$Error variable is a rich object that has many useful properties worth reading and helpful for further understanding of the error that just occurred.

Let’s see some useful properties and in section Write-ErrorLog CmdLet Explained I have explained to you some useful examples of properties that are interesting to be written in an external log file.

$error[0] | Get-Member

$Error.CategoryInfo | Get-Member

$Error[0].Exception

$Error.InvocationInfo | Get-Member

Write-Error CmdLet

Write-Error CmdLet writes an object to the error stream.

Please read this article from Microsoft PowerShell documentation regarding this CmdLet.

Handling Errors from non-PowerShell processes

We can run applications from PowerShell script like for example, PsExec.exe or robocopy.exe and they are external processes for PowerShell. Since it is an external process, errors from it will not be caught by our try/catch blocks in PowerShell script. So how we will know whether our external process was successful or not.

Well, we can use the $LastExitCode PowerShell automatic variable.

PowerShell will write the exit code to the $LastExitCode automatic variable when the external process exits. Check the external tool’s documentation for exit code values but usually, 0 means success and 1 or greater values mean a failure.

Useful PowerShell Error Handling Articles

Here are some useful articles and resources:

• Windows PowerShell Error Reporting
• About Try Catch Finally
• About CommonParameters
• About Automatic Variables
• About Preference Variables
• Write-Error
• About Throw
• About Break
• About Continue

PowerShell Pipeline

Exploring Errors in PowerShell

The first step in solving any problem is first learning why the problem occurred in the first place.

Errors happen regardless of what scripting or programming language that you use. Whether the error happens due to an issue in how the code was written or if the code is not being used in the way that it was intended. We know that errors can come in the non-terminating and terminating type as well as how to properly handle the errors when they occur. With PowerShell, not only can we handle the errors but we can also explore the error itself as it is an object like everything else in PowerShell! Using the error, we can uncover some useful things not only about the error itself, but also about what was being run at the time of the error.

First off, it is important to know that the error variable is called $Error and it is considered an automatic variable which means that you should never think about saving data to it. Doing so could have unintended issues and create more issues. $Error is also a collection which means that you can locate a specific error by an index such as the most recent error will be at the 0 index and the last error will be the final item in the collection, easily found by using -1 in the index.

throw 'this will  fail'

  1/0 

  Get-Service -Name DoesNotExist 

$Error.count 

Looking at different parts of the collection, we can see the last error that occurred, as showed by being the 0 index and the first error which is represented as -1 or in this case a 2 (remember that collections start at a 0 index). Knowing this, we can safely assume that the first item in the collection will talk about my service error that I threw and the last error will be related to a custom thrown error.

$Error[0] 

  $Error[2] 

The beauty of the $Error object is that it is in fact, an object. We can take a look at the one of the errors and begin to see what it looks like and also, depending on what caused the error, maybe use the data within the error to log to a file. A great example is working with files and folders. Let’s assume that I am performing a scan against the entire operating system drive (typically the C: drive) and I want to track any access denies that I happen to come across.

Get-ChildItem -Path c: -recurse -Force -ErrorAction SilentlyContinue |  Out-Null 

Ok, even though I am specifying the erroractionpreference value of silentlycontinue, all errors that occur will still be logged to $Error. After this has completed, we can see what paths gave us the most issues by looking only those errors that have returned access denied.

But how do we know where to look for this information? Well, we can take the first error and explore it by piping the output to something like Select-Object and specifying a * to view all of its properties.

$Error[0]  | Select-Object  -Property * 

Here we can see a lot of information with one such property being exception. This actually is an object (System.UnauthorizedAccessException) that we can test against to find all exceptions that deal with an unauthorized access exception that creates the access denied that we are seeing here.

Knowing this information, I can begin to filter out all  errors but those which have access exceptions.

  $AccessDenied = $Error | Where {

  $_.Exception -is  [System.UnauthorizedAccessException]

} 

Using the –Is operator is great way to test an object against a specific object type to determine if it is valid or not. Now we have filtered only the errors that we need and can work to further inspect the error and determine the best approach to only showing the path to the file or folder without spending a lot of time trying to parse the error using RegEx or something similar.

$AccessDenied[0]  | Select-Object  -Property * 

Again I will use Select-Object to fully display all of the properties within the error to determine if a property happens to meet what we are looking for.

Sure enough, our answer lies within the TargetObject property which happens to point to the full path of the folder that we had an issue with.

$AccessDenied[0].TargetObject
PS C:WINDOWSsystem32> $AccessDenied[0].TargetObject
 C:WindowsSysWOW64configsystemprofileAppDataLocalMicrosoftWindowsINetCacheContent.IE5

Using this, we can quickly send all of the failed attempts to a file or folder to a log file and then have a list to review and take action on, if needed.

$AccessDenied | Select-Object -ExpandProperty TargetObject  | 
 Out-File AccessIssues.txt 

This isn’t the end of the error object and its many, many uses. We can dig into another property, this time the InvocationInfo property, and determine where an error occurred within a script or function.

$AccessDenied[0].InvocationInfo 

Looking at the line number and OffsetInline, we can quickly determine where in the script or function happened and then work from there to try and resolve it.

Errors can be annoying at times, but we can make use of the rich objects that PowerShell has to explore the error and better understand what happened and maybe even use it to quickly generate useful logs to make resolving an issue much simpler.

There are a few different kinds of errors in PowerShell, and it can be a little bit of a minefield on occasion.
There are always two sides to consider, too: how you write code that creates errors, and how you handle those errors in your own code.
Let’s have a look at some ways to effectively utilise the different kinds of errors you can work with in PowerShell, and how to handle them.

Different Types of Errors

Terminating Errors

Terminating errors are mostly an «exactly what it sounds like» package in general use.
They’re very similar to C#’s Exception system, although PowerShell uses ErrorRecord as its base error object.
Their common characteristics are as follows:

• Trigger try/catch blocks
• Return control to the caller, along with the exception, if they’re not handled using a try/catch block.

There are a couple different ways to get a terminating error in PowerShell, and each has its own small differences that make them more useful in a tricky situation.

Throw

First is your typical throw statement, which simply takes an exception message as its only input.

throw "Something went wrong"

throw creates an exception and an ErrorRecord (PowerShell’s more detailed version of an exception) in a single, simple statement, and wraps them together.
Its exceptions display the entered error message, a generic RuntimeException, and the errorID matches the entered exception message.
The line number and position displayed from a throw error message point back to the throw statement itself.
throw exceptions are affected by -ErrorAction parameters of their advanced functions.

throw should generally be used for simple runtime errors, where you need to halt execution, but typically only if you plan to catch it yourself later.
There is no guarantee a user will not elect to simply ignore your error with -ErrorAction Ignore and continue with their lives if it is passed up from your functions.

ThrowTerminatingError()

Next, we have a more advanced version of the throw statement. ThrowTerminatingError() is a method that comes directly from PowerShell’s PSCmdlet .NET class.
It is accessible only in advanced functions via the $PSCmdlet variable.

using namespace System.Management.Automation;
$Exception = [Exception]::new("error message")
$ErrorRecord = [System.Management.Automation.ErrorRecord]::new(
    $Exception,
    "errorID",
    [System.Management.Automation.ErrorCategory]::NotSpecified,
    $TargetObject # usually the object that triggered the error, if possible
)
$PSCmdlet.ThrowTerminatingError($ErrorRecord)

As you can see, these require a little more manual labor.
You can bypass some of this by deliberately using the throw statement and then later catching the generated ErrorRecord to pass it into the ThrowTerminatingError() method directly.
This saves a decent amount of the code involved, and offloads the work to PowerShell’s engine instead.
However, this will still involve essentially the same work being done, without necessarily giving you a chance to specify the finer details of the error record.

ThrowTerminatingError() creates a terminating error (as the name implies), however unlike throw its errors are unaffected by -ErrorAction parameters applied to the parent function.
It will also never reveal the code around it.
When you see an error thrown via this method, it will always display only the line where the command was called, never the code within the command that actually threw the error.

ThrowTerminatingError() should generally be used for serious errors, where continuing to process in spite of the error may lead to corrupted data, and you want any specified -ErrorAction parameter to be ignored.

Non-Terminating Errors

Non-terminating errors are PowerShell’s concession demanded by the fact that it is a shell that supports pipelines.
Not all errors warrant halting all ongoing actions, and only need to inform the user that a minor error occurred, but continue processing the remainder of the items.

Unlike terminating errors, non-terminating errors:

• Do not trigger try/catch blocks.
• Do not affect the script’s control flow.

Write-Error

Write-Error is a bit like the non-terminating version of throw, albeit more versatile.
It too creates a complete ErrorRecord, which has a NotSpecified category and some predefined Exception and ErrorCode properties that both refer to Write-Error.

This is a very simple and effective way to write a non-terminating error, but it is somewhat limited in its use.
While you can override its predefined default exception type, error code, and essentially everything about the generated ErrorRecord, Write-Error is similar to throw in that it too points directly back to the line where Write-Error itself was called.
This can often make the error display very unclear, which is rarely a good thing.

Write-Error is a great way to emit straightforward, non-terminating errors, but its tendency to muddy the error display makes it difficult to recommend for any specific uses.
However, as it is itself a cmdlet, it is also possible to make it create terminating errors as well, by using the -ErrorAction Stop parameter argument.

WriteError()

WriteError() is the non-terminating cousin of ThrowTerminatingError(), and is also available as one of the members of the automatic $PSCmdlet variable in advanced functions.
It behaves similarly to its cousin in that it too hides the code that implements it and instead points back to the point where its parent function was called as the source point of the error.
This is often preferable when dealing with expected errors such as garbled input or arguments, or simple «could not find the requested item» errors in some cases.

$Exception = [Exception]::new("error message")
$ErrorRecord = [System.Management.Automation.ErrorRecord]::new(
    $Exception,
    "errorID",
    [System.Management.Automation.ErrorCategory]::NotSpecified,
    $TargetObject # usually the object that triggered the error, if possible
)
$PSCmdlet.WriteError($ErrorRecord)

Emit Errors Responsibly

There are no true hard-and-fast rules here.
If one solution works especially well for what you happen to be putting together, don’t let me deter you.
However, I would urge you to consider both the impact to your users as well as yourself or your team before selecting a single-minded approach to error creation.
Not all error scenarios are created equal, so it’s very rare that I would recommend using one type over all others.

WriteError() is generally preferred over its cmdlet form Write-Error, because it offers more control over how you emit the error.
Both tend to be used for expected and technically avoidable errors that occur, but the $PSCmdlet method has the additional benefit of not divulging implementation details unnecessarily.

If you expect the error to occur sometimes, I would generally advise using WriteError() unless the error’s presence significantly impairs your cmdlet’s ability to process the rest of its input, in which case I would use ThrowTerminatingError().

throw is generally nice as a quick way to trigger a try/catch block in your own code, but I would also recommend using it for: those truly unexpected errors, that last-ditch catch clause after several more specific catch blocks have been put in place and bypassed.
At this point, a final ending catch block that simply triggers a throw $_ call to re-throw the caught exception into the parent scope and quickly pass execution back to the caller.
It’s a very quick and very effective way to have the error be noticed, but should usually be kept internal to the function more than anything else, except in the last scenario mentioned.
Use of Write-Error -ErrorAction Stop may potentially also be substituted for that purpose if you personally prefer.

Thanks for reading!