If a Vault application that makes use of powerEvents runs into an error, there are multiple possibilities to narrow down where exactly the execution of your event scripts failed.


Problematic lines displayed in Error Message Box Details

A modal Error Message Box gets presented to the Vault user and by expanding the Details button additional important information about the error that caused the termination of the script are being displayed. This includes the name of the script or the module file where the terminating error was raised with the exact line number. In case the error was raised in a registered Vault event, the event name is also displayed.


Normally the script execution continues for non-terminating PowerShell errors, but in order to change this behavior, you can can set the $ErrorActionPreference to Stop in your event script.

Doing this will display the same Error Message Box for all non-terminating errors, even for non-terminating errors in other installed event scripts. 

$ErrorActionPreference = "Stop"

Therefore it is possible to identify such lines in your code and afterwards handle those errors, e.g. by simply using the 

-ErrorAction Continue parameter if further execution of the event script makes sense.


Identifying problematic lines via Logfile

The next step to analyze the issue is to check the powerEvents logfile. The logfiles can be accessed by clicking on the "powerEvents Logs" shortcut in the Windows Start Menu.

It provides information to determine which script is causing the error and in which line the error occurred.

In case a terminating PowerShell error got raised in a registered Vault event, the name of the event is logged as well:

2021-01-29 10:58:15,749 [Pipeline Execution Thread] ERROR coolOrange.Powershell.Hosting.Host.PowershellHost - The script execution in event script "Sample.EditItem.ps1" terminated for Vault event "EditItems_Pre" because of an error generated by script, functions or commands.
System.Management.Automation.RuntimeException: A null value was passed in where a null value is not allowed (Vault error code: 155).
   at <ScriptBlock>, C:\ProgramData\coolOrange\powerEvents\Events\Sample.EditItem.ps1: line 6

In this example the log message indicates that the event execution in the script "Sample.EditItem.ps1" terminated because a null value was passed in line 6.


Show-Inspector

The powerVault cmdlet Show-Inspector shows all the variables that are used in your event script or module. The inspector allows you to check all variables and its values at specified points in your code. In cases where your code runs into errors this can be useful to identify the cause.

The powerVault module is directly available after importing the powerEvents module.

When displaying the inspector window, the script execution gets stopped until the window is closed. You can also highlight a specific variable, like the $items parameter being passed to your registered Vault event as in the following example:

Import-Module powerEvents
Register-VaultEvent -EventName EditItems_Pre -Action {
     Show-Inspector -Highlight items
}
Since powerEvents automatically reloads scripts by default it is not needed to restart the hosting application


Using the $Host variable you can take actions like showing an inspector dialog every time a terminating PowerShell error occurs in an event script, a related module or a registered Vault event.

To do so you can modify the PrivateData property of $Host as in the following example:

$global:Host.PrivateData.OnTerminatingError = [Action[System.Management.Automation.RuntimeException]] {
   param($exception)
      Show-Inspector
}


This should only be used while analyzing errors in event scripts since it stops the execution of the job until the Inspector window is closed!

Debugging an Event script

It is possible to debug event scripts in your PowerShell IDE after importing the powerEvents Module and connecting to Vault using the Open-VaultConnection cmdlet. Your event registrations are executed after performing the same operations using powerVault cmdlets that usually are performed from your Vault users. For example updating the Number of an item in a PowerShell IDE using Update-VaultItem will trigger a registered "EditItems" event.

In order to prevent double event registrations the event script file can be moved outside of the "C:\ProgramData\coolOrange\powerEvents\Events" directory.


See Also

How to find issues in PowerShell scripts (coolOrange knowledge base)

Preference variables (Microsoft docs)