Set-ScheduledJob (PowerShell 3.0+)

Change the properties of a scheduled job.

Syntax
      Set-ScheduledJob [-InputObject] ScheduledJobDefinition [-ArgumentList Object[]]
         [-Authentication AuthenticationMechanism] [-Credential PSCredential]
            [-InitializationScript ScriptBlock] [-MaxResultCount Int32] [-Name String]
               [-PassThru] [-RunAs32] [-RunNow] [-ScheduledJobOption ScheduledJobOptions]
                  [-ScriptBlock ScriptBlock] [-Trigger ScheduledJobTrigger[]] [CommonParameters]

      Set-ScheduledJob [-InputObject] ScheduledJobDefinition [-ArgumentList Object[]]
         [-Authentication AuthenticationMechanism] [-Credential PSCredential] 
            [-InitializationScript ScriptBlock] [-MaxResultCount Int32] [-Name String]
               [-PassThru] [-RunAs32] [-RunNow] [-ScheduledJobOption ScheduledJobOptions]
                  [-FilePath String] [-Trigger ScheduledJobTrigger[]] [CommonParameters]

      Set-ScheduledJob [-InputObject] ScheduledJobDefinition [-ClearExecutionHistory]
         [-PassThru] [CommonParameters]

Key
   -ArgumentList Object[]
       Specifies 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.

   -Authentication AuthenticationMechanism
       Specifies the mechanism that is used to authenticate the user's credentials. Valid values are Default, 
       Basic, Credssp, Digest, Kerberos, Negotiate, and NegotiateWithImplicitCredential.  The default value is 
       Default. For information about the values of this parameter, see the description of the 
       System.Management.Automation.Runspaces.AuthenticationMechanism enumeration in MSDN.
 
       CAUTION: Credential Security Support 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.

   -ClearExecutionHistory
       Deletes the current execution history and the saved results of the scheduled job.
 
       The job execution history and job results are saved with the scheduled job in the 
       $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs directory 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.
 
       This parameter does not affect the events that Task Scheduler writes to the Windows event logs and it does not 
       stop Windows PowerShell from saving job results. To manage the number of job results that are saved, use the 
       MaxResultCount parameter.
 
   -Credential PSCredential
       Specifies a user account that has permission to run the scheduled job. The default is the current user.
 
       Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one from the 
       Get-Credential cmdlet. If you enter only a user name, you will be prompted for a password.
 
   -FilePath String
       Specifies 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 scheduled job must 
       have either a ScriptBlock or FilePath value.
 
   -InitializationScript ScriptBlock
       Specifies 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 does not run and its status is "Failed."
 
   -InputObject ScheduledJobDefinition
       Specifies the scheduled job to be changed. Enter a variable that contains  ScheduledJobDefinition objects or 
       type a command or expression that gets ScheduledJobDefinition objects, such as a Get-ScheduledJob command. You 
       can also pipe a ScheduledJobDefinition object to Set-ScheduledJob.
 
       If you specify multiple scheduled jobs, Set-ScheduledJob makes the same changes to all jobs.
 
    -MaxResultCount Int32
       Specifies how many job result entries are maintained for the scheduled job. The default value is 32.
 
       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.
 
   -Name String
       Specifies a new name for the scheduled job and instances of the scheduled job. The name must be unique on the 
       local computer.
 
       To identify the scheduled job to be changed, use the InputObject parameter or pipe a scheduled job from 
       Get-ScheduledJob to Set-ScheduledJob.
 
       This parameter does not change the names of job instances on disk. It affects only job instances that are 
       started after this command completes.
 
   -PassThru
       Returns the scheduled jobs that changed. By default, this cmdlet does not generate any output.
 
   -RunAs32
       Runs the scheduled job in a 32-bit process.
 
   -RunNow
       Starts a job immediately, as soon as the Set-ScheduledJob cmdlet is run. This parameter eliminates the need to 
       trigger Task Scheduler to run a Windows PowerShell script immediately after registration, and does not require 
       users to create a trigger that specifies a starting date and time.
 
   -ScheduledJobOption ScheduledJobOptions
       Sets 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 scheduled job or use the Set-ScheduledJobOption 
       or Set-ScheduledJob cmdlets to set or change 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.
 
       @{# Power SettingsStartIfOnBattery=$False;StopIfGoingOnBattery=$True; WakeToRun=$False; # Idle 
       SettingsStartIfNotIdle=$False; IdleDuration="00:10:00"; IdleTimeout="01:00:00"; StopIfGoingOffIdle=$True; 
       RestartOnIdleResume=$False;# Security settingsShowInTaskScheduler=$TrueRunElevated=$False;# 
       MiscRunWithoutNetwork=$False;DoNotAllowDemandStart=$False;MultipleInstancePolicy=IgnoreNew# Can be IgnoreNew, 
       Parallel, Queue, StopExisting}
 
   -ScriptBlock ScriptBlock
       Specifies the commands that the scheduled job runs. Enclose the commands in 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.
 
   -Trigger ScheduledJobTrigger[]
       Specifies 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 a scheduled job automatically on a one-time or recurring scheduled or when an event 
       occurs.
 
       Job triggers are optional. You can add a trigger when you create the scheduled job,  use the Add-JobTrigger or 
       Set-ScheduledJob cmdlets to add triggers later, or use the Start-Job cmdlet to start the scheduled job 
       immediately. You can also create and maintain a scheduled job that has no job triggers.
 
       To submit a hash table, use the following keys.
 
       @{Frequency="Once" (or Daily, Weekly, AtStartup, AtLogon);At="3am" (or any valid time string);
       DaysOfWeek="Monday", "Wednesday" (or any combination of day names);
       Interval=2 (or any valid frequency interval);
       RandomDelay="30minutes" (or any valid timespan string);
       User="Domain1\User01 (or any valid user; used only with the AtLogon frequency value)
       }

To use this cmdlet, begin by using Get-ScheduledJob to get the scheduled job. Then, pipe the scheduled job to Set-ScheduledJob (or save the job in a variable) and use the -InputObject parameter of Set-ScheduledJob to identify the job.

Although you can use Set-ScheduledJob to change the triggers and options of a scheduled job, the Add-JobTrigger, Set-JobTrigger, and Set-ScheduledJobOption cmdlets provide much easier ways to accomplish those tasks. To create a new scheduled job, use the Register-ScheduledJob cmdlet.

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 Start-Job to start the job immediately at any time, or save the untriggered scheduled job as a template for other jobs.

You cannot rename an existing job, instead delete the job and recreate it with a new name.

Examples

Specify a new script for the existing job ss64job:

PS C:\> Import-Module TaskScheduler
PS C:\> Get-ScheduledJob -Name ss64job | Set-ScheduledJob -FilePath C:\Scripts\demo.ps1 -Passthru

Delete the execution history of a scheduled job:

PS C:\> Get-ScheduledJob ss64job | Set-ScheduledJob -ClearExecutionHistory

Change the scheduled job 'ss64job' on several remote computers:

PS C:\> Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock {Get-ScheduledJob -Name ss64job | Set-ScheduledJob -InitializationScript \\Srv64\Scripts\demo.ps1}

“You are never too old to set another goal or to dream a new dream” ~ C.S. Lewis

Related PowerShell Cmdlets

Scheduler cmdlets - Get/Set scheduled jobs.
Add-JobTrigger - Add a job trigger to a scheduled job.
New-JobTrigger - Create a new Job Trigger.
Set-ScheduledJobOption - Change the options of a scheduled job.


 
Copyright © 1999-2024 SS64.com
Some rights reserved