Scope
- JobScheduler offers PowerShell as a language for implementation of Jobs
- The introduction of PowerShell as a language for JobScheduler has not only with API jobs to do, but can also be used a language for Shell jobs
- There are some differences between Shell and PowerShell Jobs that will be supported as they are (see PowerShell as a Shell)
- The decision to include PowerShell as a language for JobScheduler (among others) is in the same line with the development of Microsoft programming languages
- PowerShell Jobs can only be run on Agents and not on the Master
Feature Availability
FEATURE AVAILABILITY STARTING FROM RELEASE 1.10.5
Examples
Example: PowerShell as a Shell
Example 1: A simple PowerShell job with some scripting analogue to basic Shell jobs might look like this:
<?xml version="1.0" encoding="ISO-8859-1"?> <job process_class="my_Agent"> <script language="powershell"> echo "job is starting" sleep 10 $files = dir * echo $files echo "job is finishing" </script> <run_time /> </job>
Example 2: A basic PowerShell job including a call of a function might look like this:
<?xml version="1.0" encoding="ISO-8859-1"?> <job process_class="my_Agent"> <script language="powershell"> function get_files($directory){ echo "entering function get_files" return get-childitem $directory } echo "job is starting" sleep 10 $files = get_files "my_directory" echo $files echo "job is finishing" </script> <run_time /> </job>
Example: PowerShell API Jobs
A basic API Job might look like this:
<?xml version="1.0" encoding="ISO-8859-1"?> <job process_class="my_Agent"> <script language="powershell"> function spooler_process() { $spooler_log.info("job is starting") $files = get-childitem dir * echo $files $spooler_log.info("job is finishing") return $false } </script> <run_time /> </job>
For further information about how to write API Jobs in PowerShell, have a look at http://www.sos-berlin.com/doc/en/scheduler.doc/api/api-powershell.xml. You will find the available methods as well as some useful examples for your API jobs.
Example: Combination of both (PowerShell Job with Monitor as a Pre-Processing job)
This PowerShell job contains a job with a pre-processing Monitor script (API job) that is executed before the job script (the shell job) is executed:
<?xml version="1.0" encoding="ISO-8859-1"?> <job process_class="my_Agent"> <script language="powershell"> echo "job is starting" sleep 10 echo "job is finishing" </script> <monitor name="process_powershell" ordering="0"> <script language="powershell"> <![CDATA[ function spooler_process_before() { # check for a "go" file that is required to start the job $rc = (Test-Path -Path "/tmp/go.txt" -PathType Leaf) echo ".. looking up go file: $rc" return $rc } ]]> </script> </monitor> <run_time /> </job>
Example: PowerShell Job with different outputs
The following job shows how to set different outputs for PowerShell such as:
<?xml version="1.0" encoding="ISO-8859-1"?> <job process_class="my_Agent" stop_on_error="no"> <settings > <log_level ><![CDATA[debug1]]></log_level> </settings> <script language="powershell"> <![CDATA[ # Standard PowerShell verbose setting is considered for log output: $VerbosePreference = "continue" Write-Verbose "job: this is some verbose output" # Standard PowerShell debug setting: $DebugPreference = "continue" # In addition the current log level of the job is applied, e.g. log level "debug1" logs debug messages Write-Debug "job: this is some debug output" # creates a warning in the log Write-Warning "job: this is a warning" # can be used to throw an error # Write-Error "job: this is an error" # This does not work: Use of Write-Host is not allowed # Write-Host "job: this is some output" ]]> </script> <run_time /> </job>
Explanations
- Setting PowerShell verbosity for a job
- The standard PowerShell verbosity setting is considered for log output
- Use
$VerbosePreference = "Continue"
followed by theWrite-Verbose
cmdlet.
- Setting PowerShell debug messages for a job
- The standard PowerShell debug setting is ignored for jobs (
$DebugPreference = "Continue"
) - Instead, the current log level of the job is applied, e.g. log level "debug1" will log debug messages
- With the JobScheduler log level being switched to
info
no debug output is written to the log file - With the JobScheduler log level being switched to
debug1
,debug2
, ...,debug9
then debug output is added to the log. - The example shows how to set this at lines 16-17
- The standard PowerShell debug setting is ignored for jobs (
- Setting Warning Messages can be done as in line 19
- Setting Error Messages can be done as in line 22
- This throws an error and ends effectively the job with an error
Write-Host
does not work for PowerShell jobs as such jobs are not running in a PowerShell host console, but in a PowerShell run-time process.
Extras: PowerShell CLI for Powershell Jobs
The integration of the PowerShell CLI into PowerShell jobs is available as well. A basic job using the PowerShell CLI might look like this:
<job process_class="my_Agent"> <script language="powershell"> <![CDATA[ Import-Module JobScheduler show-status ]]> </script> <run_time />
- The feature is only available in case your Agent is running on a machine with PowerShell available
- For more information about how to set the PowerShell CLI modules on your Agent, have a look at PowerShell Command Line Interface - Introduction
Differences between PowerShell and Shell
As mentioned before, Powershell Jobs should be seen as the analogy for Shell Jobs in the future. That means, every Shell job should be able to be (with any or few changes) converted into a PowerShell job.
Nevertheless, there are some compatibility issues as described below.
Calling Order parameters or Job parameters
# Example Shell: myscript.cmd %SCHEDULER_PARAM_NAME1% # Example PowerShell: myscript.cmd $env:SCHEDULER_PARAM_NAME1
Returning a parameter an its value to an Order
# Example Shell: echo NAME1 = VALUE1 >> %SCHEDULER_RETURN_VALUES% # Example PowerShell: echo "NAME1 = VALUE1" >> $env:SCHEDULER_RETURN_VALUES $spooler_task.order.params.set_value( 'NAME1', 'VALUE1')
Exit Code Handling
The following example throws no error in a Shell job but it breaks at line 2 and ends in an error for a PowerShell job:
echo "job is starting" abcde echo "job is finishing"
The same example would be working in PowerShell the following way:
echo "job is starting" try { abcde } catch {} echo "job is finishing"
This type of differences described above will be further supported like this from JobScheduler and seen as natural differences between the Shell and PowerShell languages.