Register-ScheduledJob PowerShell Get-Help Output

This is the built-in help made by Microsoft for the command 'Register-ScheduledJob', in PowerShell version 4 - as retrieved from Windows version 'Microsoft Windows 8.1 Enterprise' PowerShell help files on 2016-06-23.

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.

SYNOPSIS

SYNTAX

Register-ScheduledJob [-Name] <String> [-ScriptBlock] <ScriptBlock> [-ArgumentList <Object[]>] [-Authentication <AuthenticationMechanism>] [-Credential <PSCredential>
] [-InitializationScript <ScriptBlock>] [-MaxResultCount <Int32>] [-RunAs32] [-RunNow] [-ScheduledJobOption <ScheduledJobOptions>] [-Trigger <ScheduledJobTrigger[]>]
[-Confirm] [-WhatIf] [<CommonParameters>]
Register-ScheduledJob [-Name] <String> [-FilePath] <String> [-ArgumentList <Object[]>] [-Authentication <AuthenticationMechanism>] [-Credential <PSCredential>] [-Init
ializationScript <ScriptBlock>] [-MaxResultCount <Int32>] [-RunAs32] [-RunNow] [-ScheduledJobOption <ScheduledJobOptions>] [-Trigger <ScheduledJobTrigger[]>] [-Confir
m] [-WhatIf] [<CommonParameters>]

Search powershellhelp.space

DESCRIPTION

The Register-ScheduledJob cmdlet creates scheduled jobs on the local computer.

A "scheduled job" is a Windows PowerShell background job that can be started automatically on a one-time or recurring schedule. Scheduled jobs are stored on disk and
registered in Task Scheduler, so they can be managed in Task Scheduler or by using the Scheduled Job cmdlets in Windows PowerShell.

When a scheduled job starts, it creates an "instance" of the scheduled job. Scheduled job instances are identical to Windows PowerShell background jobs, except that t
he results are saved on disk. Use the Job cmdlets, such as Start-Job, Get-Job, and Receive-Job to start, view, and get the results of the job instances.

Use Register-ScheduledJob to create a new scheduled job. To specify the commands that the scheduled job runs, use the ScriptBlock parameter; to specify a script that
the job runs, use the FilePath parameter.

Windows PowerShell scheduled jobs use the same job triggers and job options that Task Scheduler uses for scheduled tasks.

The Trigger parameter of Register-ScheduledJob adds one or more job triggers that start the job. The Trigger parameter is optional, so you can add triggers when you c
reate the scheduled job, add job triggers later, add the RunNow parameter to start the job immediately, use the Start-Job cmdlet to start the job immediately at any t
ime, or save the untriggered scheduled job as a template for other jobs.

The Options parameter lets you customize the options settings for the scheduled job. The Options parameter is also optional, so you can set job options when you creat
e the scheduled job or change them at any time. Because job option settings can prevent the scheduled job from running, review the job options and set them carefully.

Register-ScheduledJob is one of a collection of job scheduling cmdlets in the PSScheduledJob module that is included in Windows PowerShell.

For more information about Scheduled Jobs, see the About topics in the PSScheduledJob module. Import the PSScheduledJob module and then type: Get-Help about_Scheduled
* or see about_Scheduled_Jobs.

This cmdlet is introduced in Windows PowerShell 3.0.

RELATED LINKS

REMARKS

Examples

Example 1: Create a scheduled job

PS C:\>Register-ScheduledJob –Name Archive-Scripts -ScriptBlock { dir $home\*.ps1 -Recurse | Copy-Item -Destination \\Server\Share\PSScriptArchive }

This command creates the Archive-Scripts scheduled job. The ScriptBlock parameter value contains a command that searches the $home directory recursively for .ps1 file
s and copies them to a directory in a file share.

Because the scheduled job does not contain a trigger, it is not started automatically. You can use add job triggers later, use the Start-Job cmdlet to start the job o
n demand, or use the scheduled job as a template for other scheduled jobs.

Example 2: Create a scheduled job with triggers and custom options

The first command uses the New-ScheduledJobOption cmdlet to create a job option object, which it saves in the $o parameter. The options start the scheduled job even i
f the computer is not idle, wake the computer to run the job, if necessary, and allows multiple instances of the job to run in a series.
PS C:\>$o = New-ScheduledJobOption –WakeToRun –StartIfNotIdle –MultipleInstancesPolicy Queue

The second command uses the New-JobTrigger cmdlet to create job trigger that starts a job every other Monday at 9:00 p.m.
PS C:\>$t = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday –WeeksInterval 2

This command creates the UpdateVersion scheduled job, which runs the UpdateVersion.ps1 script every Monday at 9:00 p.m. The command uses the FilePath parameter to spe
cify the script that the job runs. It uses the Trigger parameter to specify the job triggers in the $t variable and the ScheduledJobOption parameter to specify the op
tion object in the $o variable.
PS C:\>Register-ScheduledJob –Name UpdateVersion –FilePath \\Srv01\Scripts\UpdateVersion.ps1 –Trigger $t –ScheduledJobOption $o

This example shows how to create a scheduled job that has a job trigger and custom job options.

Example 3: Use hash tables to specify a trigger and job options

PS C:\>Register-ScheduledJob –FilePath \\Srv01\Scripts\Update-Version.ps1 –Trigger @{Frequency=Weekly; At="9:00PM"; DaysOfWeek="Monday"; Interval=2} –ScheduledJobOpti
on @{WakeToRun; StartIfNotIdle; MultipleInstancesPolicy="Queue"}

This command is has the same effect as the command in Example 2. It creates a scheduled job, but it uses hash tables to specify the values of the Trigger and Schedule
dJobOption parameters.

Example 4: Create scheduled jobs on remote computers

PS C:\>Invoke-Command –ComputerName (Get-Content Servers.txt) –ScriptBlock {Register-ScheduledJob -Name Get-EnergyData -FilePath "\\Srv01\Scripts\Get-EnergyData.ps1"
-ScheduledJobOption $o –Trigger $t } -Credential $cred

This command creates the EnergyData scheduled job on multiple remote computers. The scheduled job runs a script that gathers raw data and saves it in a running log. T
he scheduled jobs are created on the remote computer, run on the remote computer, and store their results on the remote computer.

The command uses the Invoke-Command cmdlet to run a Register-ScheduledJob command on the computers in the Servers.txt file. The Invoke-Command command uses the Creden
tial parameter to provider the credentials of a user who has permission to create scheduled jobs on the computers in the Servers.txt file.

The Register-ScheduledJob command creates a scheduled job on the remote computer that runs the EnergyData.ps1 script on the scheduled specified by the job trigger in
the $t variable. The script is located on a file server that is available to all participating computers.

Example 5: Create a scheduled job that runs a script on remote computers

PS C:\>Register-ScheduledJob –Name CollectEnergyData –Trigger $t –MaxResultCount 99 –ScriptBlock { Invoke-Command –AsJob –ComputerName (Servers.txt) –FilePath "\\Srv0
1\Scripts\Get-EnergyData.ps1" –Credential $Admin -Authentication CredSSP }

This command uses the Register-ScheduledJob cmdlet to create the CollectEnergyData scheduled job on the local computer. The command uses the Trigger parameter to spec
ify the job schedule and the MaxResultCount parameter to increase the number of saved results to 99.

The CollectEnergyData job uses the Invoke-Command cmdlet to run the EnergyData.ps1 script as a background on the computers listed in the Servers.txt file. The Invoke-
Command command uses the AsJob parameter to create the background job object on the local computer , even though the Energydata.ps1 script runs on the remote computer
s. The command uses the Credential parameter to specify a user account that has permission to run scripts on the remote computers and the Authentication parameter wit
h a value of CredSSP to allow delegated credentials.