PS Scheduled Jobs: Exploring Your Options

Posted on June 29, 2018  •  2 minutes  • 397 words

There are a total of 13 different options you can configure using the New-ScheduledJobOption and Set-ScheduledJobOption cmdlets. All of these options have a default value, and the resulting object will list out each of them. If you do not configure an option, it is assumed that you’re happy with the default.

One example of this that may catch you out if you are working on a laptop is StartIfOnBatteries. This defaults to false and means that if your laptop isn’t plugged into AC power, your scheduled job will not run.

You can see all of the default values by creating a new job <strong>ScheduledJobOptions</strong> object.

PS C:\> New-ScheduledJobOption

StartIfOnBatteries     : False
StopIfGoingOnBatteries : True
WakeToRun              : False
StartIfNotIdle         : True
StopIfGoingOffIdle     : False
RestartOnIdleResume    : False
IdleDuration           : 00:10:00
IdleTimeout            : 01:00:00
ShowInTaskScheduler    : True
RunElevated            : False
RunWithoutNetwork      : True
DoNotAllowDemandStart  : False
MultipleInstancePolicy : IgnoreNew
JobDefinition          :

It is possible to supply a hash table of options rather than using New-ScheduledJobOption. Both of the following examples produce the same result.

PS C:\> $O = New-ScheduledJobOption -ContinueIfGoingOnBattery -StartIfOnBattery
PS C:\> Register-ScheduledJob -Name 'OptionObject' -ScheduledJobOption $O

PS C:\> $O = @{StartIfOnBatteries = $true; StopIfGoingOnBatteries = $false}
PS C:\> Register-ScheduledJob -Name 'OptionHashTable' -ScheduledJobOption $O

If you want to update a job’s options, useSet-ScheduledJobOption. This cmdlet has the same parameters as the “New” equivalent, however it also requires an existing instance of an options object. This existing object indicates which scheduled job it belongs to through the JobDefinition property.

Do be aware that turning off a Boolean option requires specifically setting that option to false. To show this in action, let’s look at how we would turn off the RunElevated option on our previously created “Update PS Help” scheduled job.

PS C:\> Get-ScheduledJobOption -Name 'Update PS Help' |
    Set-ScheduledJobOption -RunElevated:$false

The final note on options is to be aware that while some options have a value against them, they may not take effect unless another option is set to a specific value. For example, there are default values for IdleDuration and IdleTimeout but these do not come into play unless StartIfNotIdle is set to False.

Wrap Up

This was a nice short post, but I hope it was useful nonetheless. Next up we’ll be diving into schedules and recurrence.

Also, remember that if you’re looking for PowerShell help , you can always find it on Twitter using #PSHelp !