PowerShell Logo Small

about_Scheduled_Jobs_Basics



This is the built-in help made by Microsoft for the document 'about_Scheduled_Jobs_Basics', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-24.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

Search powershellhelp.space

TOPIC
about_Scheduled_Jobs_Basics

SHORT DESCRIPTION
Explains how to create and manage scheduled jobs.

LONG DESCRIPTION
This topic shows how to perform basic tasks of creating and
managing scheduled jobs. For information about more advanced
tasks, see about_Scheduled_Jobs_Advanced.

HOW TO CREATE A SCHEDULED JOB
To create a scheduled job, use the Register-ScheduledJob
cmdlet. The cmdlet requires a name and the commands or
script that the job runs. You can either run the job
immediately by adding the RunNow parameter, or create a
job trigger and set job options when you create the job
or at a later time.

To create a job that runs a script, use the FilePath
parameter to specify the path to the script file. To create
a job that runs commands, use the ScriptBlock parameter.

The following command creates the ProcessJob, which runs a
Get-Process command. This scheduled job has the default job
options and no job trigger.

PS C:\> Register-ScheduledJob -Name ProcessJob -ScriptBlock { Get-Process }

Id Name Triggers Command Enabled
-- ---- -------- ------- -------
8 ProcessJob {} Get-Process True


HOW TO CREATE A JOB TRIGGER

Job triggers start a scheduled job automatically. A job trigger
can be one-time or recurring schedule or an event, such as when
a user logs on or Windows starts. Each job can have zero, one,
or multiple job triggers.

To create a job trigger, use the New-JobTrigger cmdlet. The
following command creates a job trigger that starts a job every
Monday and Thursday at 5:00 AM. The command saves the job
trigger in the $t variable.

$t = New-JobTrigger -Weekly -DaysOfWeek "Monday", "Thursday" -At "5:00 AM"

Job triggers are optional. You can start a scheduled job at
any time by adding the RunNow parameter to your
Register-ScheduledJob command, or by using the Start-Job
cmdlets.


HOW TO ADD A JOB TRIGGER

When you add a job trigger to a scheduled job, the job trigger
is added to the scheduled job XML file for the scheduled job
and becomes part of the scheduled job.

You can add a job trigger to a scheduled job when you create
the scheduled job or at a later time and you can change the
job trigger of a scheduled job at any time.

Windows PowerShell uses some of the same job triggers that Task
Scheduler uses. For detailed information about job triggers,
see the help topic for the New-JobTrigger cmdlet.

The following command uses the Register-ScheduledJob cmdlet
to create the process job. It uses the Trigger parameter to
specify the job trigger in the $t variable.

Register-ScheduledJob -Name ProcessJob -ScriptBlock {Get-Command} -Trigger $t

You can also add a job trigger to an existing scheduled job
at any time. The following command adds the job trigger in the
$t variable to the ProcessJob scheduled job.

Add-JobTrigger -Name ProcessJob -Trigger $t

As a result of this command, the job trigger starts the
ProcessJob automatically every Monday and Thursday at 5:00 AM.


HOW TO GET A JOB TRIGGER

To get the job trigger of a scheduled job, use the
Get-JobTrigger cmdlet. Use the Name, ID, and InputObject parameters
to specify the scheduled job (not the job trigger).

The following command gets the job trigger of the ProcessJob.

PS C:\> Get-JobTrigger -Name ProcessJob

Id Frequency Time DaysOfWeek Enabled
-- --------- ---- ---------- -------
1 Weekly 11/7/2011 5:00:00 AM {Monday, Thursday} True



HOW TO CREATE JOB OPTIONS

Job options establish conditions for starting and running the
job. Every job has the default job options unless you change
them. Because job options can prevent a job from running at the
scheduled time, it is important to understand the job options
and use them carefully.

Windows PowerShell uses the same job options that Task Scheduler
uses. For detailed information about the job options, see the
help topic for the New-ScheduledJobOption cmdlet. Type "Get-Help
New-ScheduledJobOption" or see the help topic online at
http://go.microsoft.com/fwlink/?LinkID=223915.

Job options are stored in the scheduled job XML file. You can
set job options when you create a scheduled job or change them at
any time.

The following command creates a scheduled job option in which
the WakeToRun scheduled job option is set to True. The WakeToRun


option runs the scheduled job even if the computer is in the Sleep
or Hibernate state at the scheduled start time. The command saves
the job options in the $o variable.

$o = New-ScheduledJobOption -WakeToRun


HOW TO GET JOB OPTIONS

To get the job options of a scheduled job, use the
Get-ScheduledJobOption cmdlet. Use the Name, ID, and
InputObject parameters to specify the scheduled job (not
the job options).

The following command gets the job options of the ProcessJob.

PS C:\> Get-ScheduledJobOption -Name ProcessJob

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 : Microsoft.PowerShell.ScheduledJob.ScheduledJobDefinition


HOW TO CHANGE JOB OPTIONS

You can change the job options of a scheduled job when you
create a scheduled job or at any time thereafter.

The following command uses the Register-JobTrigger cmdlet
to create the process job. It uses the ScheduledJobOption
parameter to specify the job options in the $o variable.

Register-JobTrigger -Name ProcessJob -ScriptBlock {Get-Process} -ScheduledJobOption $o

You can also change the job options to an existing scheduled
job at any time. The following command uses the
Set-ScheduledJobOption cmdlet to change the value of the
WakeToRun option of the ProcessJob scheduledJob to True.

Like all of the Set cmdlets in the PSScheduledJob module,
Set-ScheduledJobOption cmdlet does not have Name or ID parameters.
You can use the InputObject parameter to specify the scheduled
job options or pipe a scheduled job from Get-ScheduledJobOption
cmdlet to Set-ScheduledJobOption.

The following command uses the Get-ScheduledJob cmdlet to get the
ProcessJob. It uses the Get-ScheduledJobOption cmdlet to get the
job options in the ProcessJob and the Set-ScheduledJobOption cmdlet
to change the WakeToRun job option in the ProcessJob to True.

Get-ScheduledJob -Name ProcessJob | Get-ScheduledJobOption | Set-ScheduledJobOption -WakeToRun





HOW TO GET SCHEDULED JOB INSTANCES

When a scheduled job is started, Windows PowerShell creates a
job instance that is similar to a standard Windows PowerShell
background job. You can use the Job cmdlets, such as Get-Job,
Stop-Job and Receive-Job to manage the job instances.

NOTE: To use the Job cmdlets on instances of scheduled jobs, the
PSScheduledJob module must be imported into the session. To
import the PSScheduledJob module, type "Import-Module PSScheduledJob"
(without quotation marks) or use any Scheduled Job cmdlet, such
as Get-ScheduledJob.

To get all instances of Windows PowerShell scheduled jobs (and
all active standard jobs), use the Get-Job cmdlet. The following
command imports the PSScheduledJob module and then gets all jobs on
the local computer.

PS C:\> Import-Module PSScheduledJob

PS C:\> Get-Job


The following command gets all instances of the ProcessJob on
the local computer.

PS C:\> Get-Job -Name ProcessJob

Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------ ----- ----------- -------- -------
45 ProcessJob PSScheduledJob Completed True localhost Get-Process
46 ProcessJob PSScheduledJob Completed True localhost Get-Process
47 ProcessJob PSScheduledJob Completed True localhost Get-Process
48 ProcessJob PSScheduledJob Completed True localhost Get-Process
49 ProcessJob PSScheduledJob Completed True localhost Get-Process
50 ProcessJob PSScheduledJob Completed True localhost Get-Process
51 ProcessJob PSScheduledJob Completed True localhost Get-Process

The default display does not show the start time, which typically
distinguishes instances of the same scheduled job.

The following command uses the Format-Table cmdlet to display the Name,
ID, and BeginTime properties of the scheduled job.

PS C:\> Get-Job ProcessJob | Format-Table -Property Name, ID, BeginTime

Name Id BeginTime
---- -- ---------
ProcessJob 43 11/2/2011 3:00:02 AM
ProcessJob 44 11/3/2011 3:00:02 AM
ProcessJob 45 11/4/2011 3:00:02 AM
ProcessJob 46 11/5/2011 3:00:02 AM
ProcessJob 47 11/6/2011 3:00:02 AM


ProcessJob 48 11/7/2011 12:00:01 AM
ProcessJob 49 11/7/2011 3:00:02 AM
ProcessJob 50 11/8/2011 3:00:02 AM


GET SCHEDULED JOB RESULTS

To get the results of an instance of a scheduled job, use the
Receive-Job cmdlet.

NOTE: To use the Job cmdlets on instances of scheduled jobs, the
PSScheduledJob module must be imported into the session. To
import the PSScheduledJob module, type "Import-Module PSScheduledJob"
(without quotation marks) or use any Scheduled Job cmdlet, such
as Get-ScheduledJob.

The following command gets the results of the newest instance of
the ProcessJob scheduled job (ID = 51)

PS C:\> Import-Module PSScheduledJob

PS C:\> Receive-Job -ID 51 -Keep

The results of scheduled jobs are saved on disk, so the Keep parameter
of Receive-Job is not required. However, without the Keep parameter,
you can get the results of a scheduled job only once in each Windows
PowerShell session. To start a new Windows PowerShell session, type
"PowerShell" or open a new Windows PowerShell window.


SEE ALSO
about_Scheduled_Jobs
about_Scheduled_Jobs_Advanced
about_Scheduled_Jobs_Troubleshooting