# Host

The automatic variable [\$Host](<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-5.1#host>) is of type [PSHost](<https://docs.microsoft.com/en-us/dotnet/api/system.management.automation.host.pshost?view=powershellsdk-1.1.0>) 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*.

## Syntax

```powershell
$Host.Name
```

:::{seealso}
For the complete list of properties and methods and for more information see: [PSHost Class](<https://docs.microsoft.com/en-us/dotnet/api/system.management.automation.host.pshost?view=powershellsdk-1.1.0>).
:::

Following properties are always available :

| Type       | Name        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Access type |
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| String     | Name        | An identifier for the PowerShell hosting application. Within [](</client_customizations>) this should be *'powerEvents Webservice Extension'*.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | read-only   |
| *PSObject* | PrivateData | Each Host can provide private data that is editable. For example the property [ErrorBackgroundColor](<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/get-host?view=powershell-5.1#example-8-set-the-background-color-for-error-messages>) that is available in several PowerShell IDEs for changing the background color of error messages.<br>The powerEvents Host allows manipulating the way how Vault users are notified about [Terminating Errors](<https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/terminating-errors?view=powershell-5.1>) using the {code}`OnTerminatingError` property. | read-write  |

## Remarks

In contrast to your PowerShell IDE the powerEvents Host redirects the written output into the [logfile](<logging:logfile>).\
The format of the output provided by the [Write-Host](<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/write-host>) cmdlet can be customised within the according [Logging](<logging:powershell ide>) sections.

### Error Notifications

By default the powerEvents host is configured to write to the logfile and display a modal Vault restrictions dialog to notify users [about erroneous](<client_customizations:errors>) scripts, modules and exceptions that were thrown by registered Vault events.\
The way how users are notified about [terminating errors](<https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/terminating-errors>) can be changed using the **PrivateData** and its {code}`OnTerminatingError` property that provides all the relevant error details:

```powershell
$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'])
	        {
	                $script = $exception.Data['RegisteredEvent'].Script.FullName
	                $vaultEventName = $exception.Data['RegisteredEvent'].Name
	                Write-Host "An unexpected error has occurred in the script '$script' 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"
	        }
}
```

### Automatic Script reloading

Changes made in the PowerShell files located in the [Events](<client_customizations:scripts>) or [Modules](<client_customizations: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](<client_customizations:scripts>) or [Modules](<client_customizations:modules>) also causes powerEvents to automatically reload the whole configuration.

Please be aware that long running operations or modal dialog boxes can block this script execution (e.g. [error dialogs](<client_customizations:errors>)).\
Changes that are saved in the meantime may then not take effect for the current script execution, and the original script execution will continue after such dialogs are closed. However, the changes will take effect immediately on the next run.\
Cmdlets such as [](<inv:powervault#code_reference/commandlets/show-inspector>) or [](<inv:powergate#code_reference/commandlets/show-bomwindow>) are an exception. They block the current script execution with the windows they show, but they still allow nested reloading of scripts (but again, PowerShell operations are only executed sequentially).

:::{note}
Similarly, also simple [Form.ShowDialog](https://learn.microsoft.com/en-us/dotnet/api/system.windows.forms.form.showdialog?view=netframework-4.7#system-windows-forms-form-showdialog) or [System.Windows.Forms.MessageBox.Show](<https://learn.microsoft.com/en-us/dotnet/api/system.windows.forms.messagebox.show?view=netframework-4.7>) usages, as well as [Window.ShowDialog](https://learn.microsoft.com/en-us/dotnet/api/system.windows.window.showdialog?view=netframework-4.7#system-windows-window-showdialog) or [System.Windows.MessageBox.Show](https://learn.microsoft.com/en-us/dotnet/api/system.windows.messagebox.show?view=netframework-4.7#system-windows-messagebox-show(system-string)) calls may not block the main window thread from processing automatic reloads.\
If these functions are used - by mistake without owner window assignment - changes at runtime might not be supported and can lead to misbehavior.\
So, as long as these dialogs are open, no automatic reload should be triggered, or a restart of the application may be necessary for all changes to take effect correctly.

We’re still working on the feature and the documentation to detail what edits are supported.
:::

Keep this functionality in mind when developing new client customizations or when saving changes in your PowerShell IDE.\
In order to disable the automatic realoding mechanism you can use the global flag {code}`$powerEvents_ReloadPsScripts` in the *Common.psm1* [Module](<client_customizations:modules>):

```powershell
$global:powerEvents_ReloadPsScripts = $false
```

After enabling the functionality again, you need to restart the application.