New-ScheduledJobOption

Syntax

New-ScheduledJobOption
   [-RunElevated]
   [-HideInTaskScheduler]
   [-RestartOnIdleResume]
   [-MultipleInstancePolicy <TaskMultipleInstancePolicy>]
   [-DoNotAllowDemandStart]
   [-RequireNetwork]
   [-StopIfGoingOffIdle]
   [-WakeToRun]
   [-ContinueIfGoingOnBattery]
   [-StartIfOnBattery]
   [-IdleTimeout <TimeSpan>]
   [-IdleDuration <TimeSpan>]
   [-StartIfIdle]
   [<CommonParameters>]

Description

The New-ScheduledJobOption cmdlet creates an object that contains advanced options for a scheduled job.

You can use the ScheduledJobOptions object that New-ScheduledJobOption returns to set job options for a new or existing scheduled job. Alternatively, you can set job options by using the Get-ScheduledJobOption cmdlet to get the job options of an existing scheduled job or by using a hash table value to represent the job options.

Without parameters, New-ScheduledJobOption generates an object that contains the default values for all of the options. Because all of the properties except for the JobDefinition property can be edited, you can use the resulting object as a template, and create standard option objects for your enterprise.

When creating scheduled jobs and setting scheduled job options, review the default values of all scheduled job options. Scheduled jobs run only when all conditions set for their execution are satisfied.

New-ScheduledJobOption 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 was introduced in Windows PowerShell 3.0.

Examples

Example 1: Create a scheduled job option object with default values

PS C:\> New-ScheduledJobOption
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 : Ignore
NewJobDefinition       :

This command creates a scheduled job option object that has all of the default values.

Example 2: Create a scheduled job option object with custom values

PS C:\> New-ScheduledJobOption -RequireNetwork -StartIfOnBattery
StartIfOnBatteries     : True
StopIfGoingOnBatteries : True
WakeToRun              : False
StartIfNotIdle         : True
StopIfGoingOffIdle     : False
RestartOnIdleResume    : False
IdleDuration           : 00:10:00
IdleTimeout            : 01:00:00
ShowInTaskScheduler    : True
RunElevated            : False
RunWithoutNetwork      : False
DoNotAllowDemandStart  : False
MultipleInstancePolicy : Ignore
NewJobDefinition       :

The following command creates a scheduled job object that requires the network and runs the scheduled job even if the computer is not connected to AC power.

The output shows that the RequireNetwork parameter changed the value of the RunWithoutNetwork property to $False and the StartIfOnBattery parameter changed the value of the StartIfOnBatteries property to $True.

Example 3: Set options for a new scheduled job

The first command creates a **ScheduledJobOptions** object with the *RunElevated* parameter. It saves the object in the $RunAsAdmin variable.
PS C:\> $RunAsAdmin = New-ScheduledJobOption -RunElevated

The second command uses the Register-ScheduledJob cmdlet to create a new scheduled job. The value of the *ScheduledJobOption* parameter is the option object in the value of the $RunAsAdmin variable.
PS C:\> Register-ScheduledJob -Name Backup -FilePath D:\Scripts\Backup.ps1 -Trigger $Mondays -ScheduledJobOption $RunAsAdmin

The third command uses the Get-ScheduledJobOption cmdlet to get the job options of the Backup scheduled job.The cmdlet output shows that the RunElevated property is set to $True and the JobDefinition property of the job option object is now populated with the scheduled job object for the Backup scheduled job.
PS C:\> Get-ScheduledJobOption -Name Backup
StartIfOnBatteries     : False
StopIfGoingOnBatteries : True
WakeToRun              : False
StartIfNotIdle         : True
StopIfGoingOffIdle     : False
RestartOnIdleResume    : False
IdleDuration           : 00:10:00
IdleTimeout            : 01:00:00
ShowInTaskScheduler    : True
RunElevated            : True
RunWithoutNetwork      : True
DoNotAllowDemandStart  : False
MultipleInstancePolicy : IgnoreNew
JobDefinition          : Microsoft.PowerShell.ScheduledJob.ScheduledJobDefinition

This example shows how to use the ScheduledJobOptions object that New-ScheduledJobOption returns to set the options for a new scheduled job.

Example 4: Sort the properties of a scheduled job option object

PS C:\> $Options = New-ScheduledJobOption -WakeToRun
PS C:\> $Options.PSObject.Properties | Sort-Object -Property Name | Format-Table -Property Name, Value -Autosize
Name                       Value
----                       -----
DoNotAllowDemandStart      False
IdleDuration            00:10:00
IdleTimeout             01:00:00
JobDefinition
MultipleInstancePolicy IgnoreNew
RestartOnIdleResume        False
RunElevated                False
RunWithoutNetwork           True
ShowInTaskScheduler         True
StartIfNotIdle              True
StartIfOnBatteries         False
StopIfGoingOffIdle         False
StopIfGoingOnBatteries      True
WakeToRun                   True

This example shows how to sort the properties of a ScheduledJobOptions object in alphabetical order for easy reading.

The first command uses the New-ScheduledJobOption cmdlet to create a ScheduledJobOptions object. The command uses the WakeToRun parameter and saves the resulting object in the $Options variable.

To get the properties of $Options as objects, the second command uses the PSObject property of all Windows PowerShell objects and its Properties property. The command then pipes the property objects to the Sort-Object cmdlet, which sorts the properties in alphabetical order by name, and then to the Format-Table cmdlet, which displays the names and values of the properties in a table.

This format makes it much easier to find the WakeToRun property of the ScheduledJobOptions object in $Options and to verify that its value was changed from $False to $True.

Parameters

-ContinueIfGoingOnBattery

-DoNotAllowDemandStart

-HideInTaskScheduler

-IdleDuration

-IdleTimeout

-MultipleInstancePolicy

-RequireNetwork

-RestartOnIdleResume

-RunElevated

-StartIfIdle

-StartIfOnBattery

-StopIfGoingOffIdle

-WakeToRun

Inputs

None

You cannot pipe input to this cmdlet.

Outputs

ScheduledJobOptions

Notes

• You can use the ScheduledJobOptions object that New-ScheduledJobOption creates as the value of the ScheduledJobOption parameter of the Register-ScheduledJob cmdlet. However, the ScheduledJobOption parameter can also take a hash table value that specifies the properties of the ScheduledJobOptions object and their values, such as:

  @{ShowInTaskScheduler=$False; RunElevated=$True; IdleDuration="00:05"}

Related Links

• about_Scheduled_Jobs
• Add-JobTrigger
• Disable-JobTrigger
• Disable-ScheduledJob
• Enable-JobTrigger
• Enable-ScheduledJob
• Get-JobTrigger
• Get-ScheduledJob
• Get-ScheduledJobOption
• New-JobTrigger
• New-ScheduledJobOption
• Register-ScheduledJob
• Remove-JobTrigger
• Set-JobTrigger
• Set-ScheduledJob
• Set-ScheduledJobOption
• Unregister-ScheduledJob