CmdID / PowerShell / Cmdlets / Register
Register-ScheduledJob
Creates a scheduled job. PowerShell reference
From the PowerShell reference 15 parameters
What it does
Creates a scheduled job. 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. The jobs 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 the 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 create 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 time, 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 optional, so you can set job options when you create 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 articles in the PSScheduledJob module. Import the PSScheduledJob module and then type: Get-Help about_Scheduled* or see about_Scheduled_Jobs. This cmdlet was introduced in Windows PowerShell 3.0.
Register-ScheduledJob [-ScriptBlock] <ScriptBlock> [-Name] <String> [-Trigger <ScheduledJobTrigger[]>] [-InitializationScript <ScriptBlock>] [-RunAs32] [-Credential <PSCredential>] [-Authentication <AuthenticationMechanism>] [-ScheduledJobOption <ScheduledJobOptions>] [-ArgumentList <Object[]>] [-MaxResultCount <Int32>] [-RunNow] [-RunEvery <TimeSpan>] [-WhatIf] [-Confirm] [<CommonParameters>]Register-ScheduledJob [-FilePath] <String> [-Name] <String> [-Trigger <ScheduledJobTrigger[]>] [-InitializationScript <ScriptBlock>] [-RunAs32] [-Credential <PSCredential>] [-Authentication <AuthenticationMechanism>] [-ScheduledJobOption <ScheduledJobOptions>] [-ArgumentList <Object[]>] [-MaxResultCount <Int32>] [-RunNow] [-RunEvery <TimeSpan>] [-WhatIf] [-Confirm] [<CommonParameters>]Create a scheduled job
Register-ScheduledJob -Name "Archive-Scripts" -ScriptBlock {
Get-ChildItem $HOME\*.ps1 -Recurse |
Copy-Item -Destination "\\Server\Share\PSScriptArchive"
}IdentifyCreate a scheduled job with triggers and custom options
$O = New-ScheduledJobOption -WakeToRun -StartIfIdle -MultipleInstancePolicy Queue
$T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2
$path = "\\Srv01\Scripts\UpdateVersion.ps1"
Register-ScheduledJob -Name "UpdateVersion" -FilePath $path -ScheduledJobOption $O -Trigger $TIdentifyUse hash tables to specify a trigger and scheduled job options
$T = @{
Frequency="Weekly"
At="9:00PM"
DaysOfWeek="Monday"
Interval=2
}
$O = @{
WakeToRun=$true
StartIfNotIdle=$false
MultipleInstancePolicy="Queue"
}
$registerScheduledJobSplat = @{
Trigger = $T
ScheduledJobOption = $O
Name = 'UpdateVersion'
FilePath = "\\Srv01\Scripts\Update-Version.ps1"
}
Register-ScheduledJob @registerScheduledJobSplatIdentifyCreate scheduled jobs on remote computers
$Cred = Get-Credential
$O = New-ScheduledJobOption -WakeToRun -StartIfIdle -MultipleInstancePolicy Queue
$T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2
Invoke-Command -ComputerName (Get-Content Servers.txt) -Credential $Cred -ScriptBlock {
$params = @{
Name = "Get-EnergyData"
FilePath = "\\Srv01\Scripts\Get-EnergyData.ps1"
ScheduledJobOption = $Using:O
Trigger = $Using:T
}
Register-ScheduledJob @params
}IdentifyCreate a scheduled job that runs a script on remote computers
$Admin = Get-Credential
$T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2
Register-ScheduledJob -Name "CollectEnergyData" -Trigger $T -MaxResultCount 99 -ScriptBlock {
$params = @{
AsJob = $true
ComputerName = (Get-Content Servers.txt)
FilePath = '\\Srv01\Scripts\Get-EnergyData.ps1'
Credential = $Using:Admin
Authentication = 'CredSSP'
}
Invoke-Command @params
}IdentifyIts page in the reference: Register-ScheduledJob.
Parameters
-ArgumentListSpecifies values for the parameters of the script that is specified by the FilePath parameter or for the command that is specified by the ScriptBlock parameter.-AuthenticationSpecifies the mechanism that is used to authenticate the user's credentials. The default value is Default.
The acceptable values for this parameter are:
- Default
- Basic
- Credssp
- Digest
- Kerberos
- Negotiate
- NegotiateWithImplicitCredential
For more information about the values of this parameter, see AuthenticationMechanism.
CAUTION: Credential Security Service Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. This mechanism increases the security risk of the remote operation. If the remote computer is compromised, the credentials that are passed to it can be used to control the network session.-CredentialSpecifies a user account that has permission to run the scheduled job. The default is the current user.
Credentials are stored in a PSCredential object and the password is stored as a SecureString.
NOTE: For more information about SecureString data protection, see How secure is SecureString?.-FilePathSpecifies a script that the scheduled job runs. Enter the path to a .ps1 file on the local computer. To specify default values for the script parameters, use the ArgumentList parameter. Every Register-ScheduledJob command must use either the ScriptBlock or FilePath parameters.-InitializationScriptSpecifies the fully qualified path to a Windows PowerShell script (.ps1). The initialization script runs in the session that is created for the background job before the commands that are specified by the ScriptBlock parameter or the script that is specified by the FilePath parameter. You can use the initialization script to configure the session, such as adding files, functions, or aliases, creating directories, or checking for prerequisites.
To specify a script that runs the primary job commands, use the FilePath parameter.
If the initialization script generates an error, even a non-terminating error, the current instance of the scheduled job doesn't run and its status is Failed.-MaxResultCountSpecifies how many job result entries are maintained for the scheduled job. The default value is 32.
Windows PowerShell saves the execution history and results of each triggered instance of the scheduled job on disk. The value of this parameter determines the number of job instance results that are saved for this scheduled job. When the number of job instance results exceeds this value, Windows PowerShell deletes the results of the oldest job instance to make room for the results of the newest job instance.
The job execution history and job results are saved in the
$HOME\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\<JobName>\Output\<Timestamp>
directories on the computer on which the job is created. To see the execution history, use the
Get-Job cmdlet. To get the job results, use the Receive-Job cmdlet.
The MaxResultCount parameter sets the value of the ExecutionHistoryLength property of the scheduled job.
To delete the current execution history and job results, use the ClearExecutionHistory parameter of the Set-ScheduledJob cmdlet.-NameSpecifies a name for the scheduled job. The name is also used for all started instances of the scheduled job. The name must be unique on the computer. This parameter is required.-RunAs32Runs the scheduled job in a 32-bit process.-RunEveryUsed to specify how often to run the job. For example, use this option to run a job every 15 minutes.-RunNowStarts a job immediately, as soon as the Register-ScheduledJob cmdlet is run. This parameter eliminates the need to trigger Task Scheduler to run a Windows PowerShell script immediately after registration, and doesn't require users to create a trigger that specifies a starting date and time.-ScheduledJobOptionSets options for the scheduled job. Enter a ScheduledJobOptions object, such as one that you create by using the New-ScheduledJobOption cmdlet, or a hash table value.
You can set options for a scheduled job when you register the schedule job or use the
Set-ScheduledJobOption or Set-ScheduledJob cmdlets to change the options.
Many of the options and their default values determine whether and when a scheduled job runs. Be sure to review these options before scheduling a job. For a description of the scheduled job options, including the default values, see New-ScheduledJobOption.
To submit a hash table, use the following keys. In the following hash table, the keys are shown with their default values.
@{StartIfOnBattery=$false; StopIfGoingOnBattery=$true; WakeToRun=$false; StartIfNotIdle=$false; IdleDuration="00:10:00"; IdleTimeout="01:00:00"; StopIfGoingOffIdle=$true; RestartOnIdleResume=$false; ShowInTaskScheduler=$true; RunElevated=$false; RunWithoutNetwork=$false; DoNotAllowDemandStart=$false; MultipleInstancePolicy="IgnoreNew"}-ScriptBlockSpecifies the commands that the scheduled job runs. Enclose the commands in curly braces ({}) to create a script block. To specify default values for command parameters, use the ArgumentList parameter.
Every Register-ScheduledJob command must use either the ScriptBlock or FilePath parameters.-TriggerSpecifies the triggers for the scheduled job. Enter one or more ScheduledJobTrigger objects, such as the objects that the New-JobTrigger cmdlet returns, or a hash table of job trigger keys and values.
A job trigger starts the schedule job. The trigger can specify a one-time or recurring scheduled or an event, such as when a user logs on or Windows starts.
The Trigger parameter is optional. You can add a trigger when you create the scheduled job, use the Add-JobTrigger, Set-JobTrigger, or Set-ScheduledJob cmdlets to add or change job triggers later, or use the Start-Job cmdlet to start the scheduled job immediately. You can also create and maintain a scheduled job without a trigger that is used as a template.
To submit a hash table, use the following keys:
- Frequency: Daily, Weekly, AtStartup, AtLogon
- At: Any valid time string
- DaysOfWeek - Any combination of day names
- Interval - Any valid frequency interval
- RandomDelay: Any valid timespan string
- User: Any valid user. Used only with the AtLogon frequency value
For example:
@{Frequency="Once"; At="3am"; DaysOfWeek="Monday", "Wednesday"; Interval=2; RandomDelay="30minutes"; User="Domain1\User01"}-ConfirmPrompts you for confirmation before running the cmdlet.-WhatIfShows what would happen if the cmdlet runs. The cmdlet isn't run.