Host

The automatic variable $Host is of type PSHost and represents the current host application for PowerShell which in context of powerJobs this can be either the JobHandler or your powershell IDE.

The object also provides access to all the Applications that can be used by the commandlets Open-Document, Export-Document and Close-Document.

Syntax

$Host.Applications['Application Name']

Remarks

Such as your powershell IDE even the powerJobs Processor Host displays the written output to the user in a designated Trace Window.
The format of the output provided by the Write-Host cmdlet can be customized within the according Logging sections.
In addition to the Applications hold by the $Host variable the coolOrange.Applications.psm1 module provides additionally functions to simplify the access:

Get-Application can be used to retrieve an application by name, e.g.:
1
$inventor = Get-Application 'Inventor'
Test-ApplicationInstalled can be used to check whether the required application is installed on the Job Processor machine:
```
if(-not Test-ApplicationInstalled 'Inventor') {
  throw("Inventor is not installed on this machine!")
}
```
Test-ApplicationSupportsDocument can be used for checking if a specific application can open the document. A common use case is e.g. to check whether a dwg file is an Inventor DWG or not:
```
if(Test-ApplicationSupportsDocument -Application 'Inventor' -Document 'C:\Vault\Designs\Inventor.dwg') {
  Write-Host "This is an Inventor DWG file"
}
```

Registration

The default applications are registered in the coolOrange.Applications.psm1 module with the following lines:

Register-Application ([powerJobs.Application.Inventor.Application])
Register-Application ([powerJobs.Application.Inventor.Server.Application])
Register-Application ([powerJobs.Application.TrueView.Application])

The function Register-Application needs the type of application to be passed, in order to register the application globally.
It can also be used if you want to create your own IApplication implementation, for instance when special file extensions needs to be supported or when custom file exports are required.

Order:
When multiple registered applications are supporting the same format, powerJobs Processor will use the first found Application.
Therefore, if you prefer to use e.g. InventorServer as default over Inventor, then just switch the registration lines, so that InventorServer is registered first:

Register-Application ([powerJobs.Application.Inventor.Server.Application])
Register-Application ([powerJobs.Application.Inventor.Application])

Automatic Restart

PowerJobs Processor handles the starting and stopping of the registered applications due these cases:

timer interval
limit of close documents

Timer interval:
Each application has as timer interval, by default this setting is set to 30 minutes.
This settings can be changed in the Setup_job.ps1 file for a specific application:

$inventor = Get-Application 'Inventor'
$inventor.RestartOptions.Interval = [timespan]::FromSeconds(60)

The timer starts with the configured interval, when the first open-document call is made.
When the timer expires and the application is not busy (has no open documents), the application will be restarted immediately. Otherwise the restart for the application will be reserved.
This means that on the next Open-Document call that uses this application, it will be restarted. Watch out, again: only if the application has no open documents!

Limit of close documents:
Each application has a limit of close documents, the default value is set to 10.
This settings can be changed in the Setup_job.ps1 file for a specific application:

$inventor = Get-Application 'Inventor'
$inventor.RestartOptions.DocumentCloseCounts= 31

Every time a document gets closed this documentCloseCount increments as long as it reaches the configured limit. Then, the restart of this application will be reserved.
This means on the next Open-Document call that uses this application, it will be restarted.

Only if the applications has no open documents! Otherwise the restart remains reserved as long as a restart is allowed.

The restarts will be reserved, in order to not restart itself and close the open documents.
This could cause issues, when opening many documents one after another and the timer expires, or the closeCounter is reached.

Error Notifications

By default the powerJobs Processor host is configured to notify about failing jobs by writing exception details to the Job Queue Result as well as to the Trace Window and logfile.

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

$global:Host.PrivateData.OnTerminatingError = [System.Delegate]::Combine([Action[System.Management.Automation.RuntimeException]] {
	param($terminatingError)
	show-inspector 'terminatingError'
}, $global:Host.PrivateData.OnTerminatingError)

Type	Name	Description	Access type
String	Name	An identification for the PowerShell hosting application. Within powerJobs Processor jobs this should be ‘powerJobs JobHandler Extension’.	read-only
IDictionary<string, IApplication>	Applications	A dictionary of registered applications. A list of default applications can be found here.	read-only
PSObject	PrivateData	Each 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 powerJobs Processor Host allows extending the way how Vault users are notified about Terminating Errors using the `OnTerminatingError` property.	read-write