How to find issues in powerEvents scripts

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"

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

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
}

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
}