Change the options of a scheduled job.
Syntax
Set-ScheduledJobOption [-InputObject] ScheduledJobOptions [-ContinueIfGoingOnBattery]
[-DoNotAllowDemandStart] [-HideInTaskScheduler] [-IdleDuration TimeSpan]
[-IdleTimeout TimeSpan] [-MultipleInstancePolicy TaskMultipleInstancePolicy]
[-PassThru] [-RequireNetwork] [-RestartOnIdleResume] [-RunElevated] [-StartIfIdle]
[-StartIfOnBattery] [-StopIfGoingOffIdle] [-WakeToRun] [CommonParameters]
Key
ScheduledJobOptions
To change the options of a scheduled job, use Get-ScheduledJobOption to get the current job options of a
scheduled job. Then, pipe the options to Set-ScheduledJobOption or save the options in a variable and use
the -InputObject parameter to identify the options. Use the remaining parameters of Set-ScheduledJobOption
to change the job options. To turn on a job option, use the parameter that sets that option.
To turn off an option, type the parameter name, a colon (:), and $false.
For example, to turn off the -RunElevated option, type -RunElevated:$false.
-ContinueIfGoingOnBattery
Do not stop the scheduled job if the computer switches to battery power (disconnects from AC power) while the
job is running. By default, scheduled jobs stop when the computer disconnects from AC power.
The ContinueIfGoingOnBattery parameter sets the value of the StopIfGoingOnBatteries property of scheduled jobs
to True.
-DoNotAllowDemandStart
Start the job only when it is triggered. Users cannot start the job manually, such as by using the Run feature
in Task Scheduler.
This parameter only affects Task Scheduler. It does not prevents users from using the Start-Job cmdlet to
start the job.
The DoNotAllowDemandStart parameter sets the value of the DoNotAllowDemandStart property of scheduled jobs to
True.
-HideInTaskScheduler
Do not display the job in Task Scheduler. This value affects only the computer on which the job runs. By
default, scheduled tasks appear in Task Scheduler.
Even if a task is hidden, users can display the task by selecting the "Show hidden tasks" view option in Task
Scheduler.
The HideInTaskScheduler parameter sets the value of the ShowInTaskScheduler property of scheduled jobs to
False.
-IdleDuration TimeSpan
Specifies how long the computer must be idle before the job starts. The default value is 10 minutes. If the
computer is not idle for the specified duration before the value of IdleTimeout expires, the scheduled job
does not run until the next scheduled time, if any.
Enter a timespan object, such as one generated by the New-TimeSpan cmdlet, or enter a value in
hours:minutes:seconds format that is automatically converted to a timespan object
To enable this value, use the StartIfIdle parameter. By default, the StartIfNotIdle property of scheduled jobs
is set to True and Windows PowerShell ignores the IdleDuration and IdleTimeout values.
-IdleTimeout TimeSpan
Specifies how long the computer must be idle before the job starts. The default value is 10 minutes. If the
computer is not idle for the specified duration before the value of IdleTimeout expires, the scheduled job
does not run until the next scheduled time, if any.
Enter a timespan object, such as one generated by the New-TimeSpan cmdlet, or enter a value in
hours:minutes:seconds format that is automatically converted to a timespan object.
To enable this value, use the StartIfIdle parameter. By default, the StartIfNotIdle property of scheduled jobs
is set to True and Windows PowerShell ignores the IdleDuration and IdleTimeout values.
-InputObject ScheduledJobOptions
Specifies the job options. Enter a variable that contains ScheduledJobOptions objects or type a command or
expression that gets ScheduledJobOptions objects, such as a Get-ScheduledJobOption command. You can also pipe
a ScheduledJobOptions object to Set-ScheduledJobOption.
-MultipleInstancePolicy TaskMultipleInstancePolicy
Determines how the system responds to a request to start an instance of a scheduled job while another instance
of the job is running. The default value is IgnoreNew.
Valid values are:
-- IgnoreNew: The new job instance is ignored. This is the default value.
-- Parallel: The new job instance starts immediately.
-- Queue: The new job instance starts as soon as the current instance completes.
-- StopExisting: The current instance of the job stop and the new instance starts.
To run the job, all conditions for the job schedule must be met. For example, if the conditions that are set
by the RequireNetwork, IdleDuration and IdleTimeout parameters are not satisfied, the job instance is not
started, regardless of the value of this parameter.
-PassThru
Returns the job options that changed. By default, this cmdlet does not generate any output.
-RequireNetwork
Runs the scheduled job only when network connections are available.
If you specify this parameter and the network is not available at the scheduled start time, the job does not
run until the next scheduled start time, if any.
The RequireNetwork parameter sets the value of the RunWithoutNetwork property of scheduled jobs to False.
-RestartOnIdleResume
Restarts a scheduled job when the computer becomes idle. This parameter works with the StopIfGoingOffIdle
parameter, which suspends a running scheduled job if the computer becomes active (leaves the idle state).
The RestartOnIdleResume parameter sets the value of the RestartOnIdleResume property of scheduled jobs to True.
-RunElevated
Run the scheduled job with the permissions of a member of the Administrators group on the computer on which
the job runs.
To enable a scheduled job to run with Administrator permissions, use the Credential parameter of
Register-ScheduledJob to provide explicit credential for the job.
The RunElevated parameter sets the value of the RunElevated property of scheduled jobs to True.
-StartIfIdle
Starts the scheduled job if the computer has been idle for the time specified by the IdleDuration parameter
before the time specified by the IdleTimeout parameter expires.
By default, the IdleDuration and IdleTimeout parameters are ignored and the job starts at the scheduled start
time even if the computer is busy.
If you specify this parameter and the computer is busy (not idle) at the scheduled start time, the job does
not run until the next scheduled start time, if any.
The StartIfIdle parameter sets the value of the StartIfNotIdle property of scheduled jobs to False.
-StartIfOnBattery
Starts the scheduled job even if the computer is running on batteries at the scheduled start time. The default
value is False.
The StartIfOnBattery parameter sets the value of the StartIfOnBatteries property of scheduled jobs to True.
-StopIfGoingOffIdle
Suspends a running scheduled job if the computer becomes active (not idle) while the job is running.
By default, a scheduled job that is suspended when the computer becomes active resumes when the computer
becomes idle again. To change this default behavior, use the RestartOnIdleResume parameter.
The StopIfGoingOffIdle parameter sets the value of the StopIfGoingOffIdle property of scheduled jobs to True.
-WakeToRun
Wakes the computer from a Hibernate or Sleep state at the scheduled start time so it can run the job. By
default, if the computer is in a Hibernate or Sleep state at the scheduled start time, the job does not run.
The WakeToRun parameter sets the value of the WakeToRun property of scheduled jobs to True.
CommonParameters:
-Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer -PipelineVariable, -OutVariable.
To change the options of a scheduled job, begin by using the Get-ScheduledJobOption cmdlet to get the job options of a scheduled job. Then, pipe the options to Set-ScheduledJobOption or save the options in a variable and use the InputObject parameter of Set-ScheduledJobOption cmdlet to identify the options.
To turn on a job option, use the parameter that sets that option. To turn off an option, type the parameter name, a colon (:), and $false. For example, to turn off the -RunElevated option, type -RunElevated:$false.
The scheduled job options determine how the job runs when it is started by Task Scheduler.
These options do not apply when you use Start-Job to start a scheduled job.
Examples
Get the job options of ss64job:
PS C:\> Import-Module TaskScheduler
PS C:\> Get-ScheduledJobOption -Name ss64job
Change the job options so the values of the WakeToRun and RunWithoutNetwork properties are True:
PS C:\> Get-ScheduledJobOption -Name ss64job | Set-ScheduledJobOption -WakeToRun -RequireNetwork:$False -Passthru
Changes the value of the IdleTimeout from one hour (the default) to two hours on all scheduled jobs on the Server64:
PS C:\> Invoke-Command -Computer Server64 -ScriptBlock {Get-ScheduledJob | Get-ScheduledJobOption | Set-ScheduledJobOption -IdleTimeout 2:00:00}
“You were born to win, but to be a winner, you must plan to win, prepare to win, and expect to win” ~ Zig Ziglar
Related PowerShell Cmdlets:
Scheduler cmdlets - Get/Set scheduled jobs.
Get-ScheduledJobOption - Get the options of scheduled job.