powerevents:code_reference:objects:host

Host

The automatic variable $Host is of type PSHost and represents the current host application for PowerShell.

Within the context of powerEvents this can either be the Vault WebServiceExtension running an extended Host version or your PowerShell IDE.

$Host.Name

For the complete list of properties and methods and for more information see: PSHost Class.

Following properties are always available :

TypeNameDescriptionAccess type
stringName An identifier for the PowerShell hosting application.
Within event scripts this should be 'powerEvents Webservice Extension'.
read-only
PSObjectPrivateDataEach Host can provide private data that is editable. For example the property ErrorBackgroundColor that is available in several PowerShell IDEs for changing the background color of error messages.
The powerEvents Host allows manipulating the way how Vault users are notified about Terminating Errors using the OnTerminatingError property.
read-write

In contrast to your PowerShell IDE the powerEvents Host redirects the written output into the logfile.
The format of the output provided by the Write-Host cmdlet can be customised within the according Logging sections.

By default the powerEvents host is configured to write to the logfile and display a modal Vault restrictions dialog to notify users about erroneous event scripts, modules and exceptions that were thrown by registered Vault events.

The way how users are notified about terminating errors can be changed using the PrivateData and its OnTerminatingError property that provides all the relevant error details:

$global:Host.PrivateData.OnTerminatingError = [Action[System.Management.Automation.RuntimeException]] {
  param($exception)
     $errorType = $exception.GetType().FullName
     $errorMessage = $exception.Message
     $errorStackTrace = $exception.ErrorRecord.ScriptStackTrace

     if($exception.Data['RegisteredEvent'])
     {
           $eventScript = $exception.Data['RegisteredEvent'].Script.FullName
           $vaultEventName = $exception.Data['RegisteredEvent'].Name
           Write-Host "An unexpected error has occurred in the event script '$eventScript' for Vault event '$vaultEventName'.`r`n$errorType : $errorMessage`r`n$errorStackTrace"
     }
     else
     {
           Write-Host "An unexpected error has occurred in the script or module '$($exception.ErrorRecord.InvocationInfo.ScriptName)'`r`n$errorType : $errorMessage`r`n$errorStackTrace"
     }
}

Changes made in the PowerShell files located in the Events or Modules folder are loaded by the powerEvents Host at every start.

Also when the files are modified while they are loaded, powerEvents automatically executes them again. Restarting your application is not required.
Adding or removing Scripts or Modules also causes powerEvents to automatically reload the whole configuration.
Keep this functionality in mind when developing new event scripts or saving changes in your PowerShell IDE.

In order to disable this functionality you can use the global flag $powerEvents_ReloadPsScripts in the Common.psm1 Module:

$global:powerEvents_ReloadPsScripts = $false
After enabling this functionality again, you need to restart the application.