New-ScheduledTaskTrigger

  • Reference
Module:
ScheduledTasks

Creates a scheduled task trigger object.

Syntax

New-ScheduledTaskTrigger
   [-RandomDelay <TimeSpan>]
   -At <DateTime>
   [-Once]
   [-RepetitionDuration <TimeSpan>]
   [-RepetitionInterval <TimeSpan>]
   [-CimSession <CimSession[]>]
   [-ThrottleLimit <Int32>]
   [-AsJob]
   [<CommonParameters>]
New-ScheduledTaskTrigger
   [-Daily]
   [-DaysInterval <UInt32>]
   [-RandomDelay <TimeSpan>]
   -At <DateTime>
   [-CimSession <CimSession[]>]
   [-ThrottleLimit <Int32>]
   [-AsJob]
   [<CommonParameters>]
New-ScheduledTaskTrigger
   [-RandomDelay <TimeSpan>]
   -At <DateTime>
   [-DaysOfWeek <DayOfWeek[]>]
   [-Weekly]
   [-WeeksInterval <UInt32>]
   [-CimSession <CimSession[]>]
   [-ThrottleLimit <Int32>]
   [-AsJob]
   [<CommonParameters>]
New-ScheduledTaskTrigger
   [-RandomDelay <TimeSpan>]
   [-AtStartup]
   [-CimSession <CimSession[]>]
   [-ThrottleLimit <Int32>]
   [-AsJob]
   [<CommonParameters>]
New-ScheduledTaskTrigger
   [-RandomDelay <TimeSpan>]
   [-AtLogOn]
   [-User <String>]
   [-CimSession <CimSession[]>]
   [-ThrottleLimit <Int32>]
   [-AsJob]
   [<CommonParameters>]

Description

The New-ScheduledTaskTrigger cmdlet creates and returns a new scheduled task trigger object.

You can use a time-based trigger or an event-based trigger to start a task. Time-based triggers include starting a task at a specific time or starting a task multiple times on a daily or weekly schedule. Event-based triggers include starting a task when the system starts up or when a user logs on to the computer. Each task can contain one or more triggers, which means there are many ways that you can start a task. If a task has multiple triggers, Task Scheduler starts the task when any of the triggers occur.

Examples

Example 1: Register a scheduled task that starts a task once

PS C:\>$Sta = New-ScheduledTaskAction -Execute "Cmd"
PS C:\>$Stt = New-ScheduledTaskTrigger -Once -At 3am
PS C:\>Register-ScheduledTask Task01 -Action $Sta -Trigger $Stt

This example registers a scheduled task that starts once.

The first command creates a scheduled task action named Cmd and assigns the ScheduledTaskAction object to the $Sta variable. The second command creates a scheduled task trigger that starts the task once at 3:00 A.M and assigns the ScheduledTaskTrigger object to the $Stt variable. The third command registers the scheduled task Task01 to run the task action named Cmd once at 3:00 A.M.

Example 2: Register a scheduled task that starts every day

PS C:\>$Sta = New-ScheduledTaskAction -Execute "Cmd"
PS C:\>$Stt = New-ScheduledTaskTrigger -Daily -At 3am
PS C:\>Register-ScheduledTask Task01 -Action $Sta -Trigger $Stt

This example registers a scheduled task that starts every day.

The first command creates a scheduled task action named Cmd and assigns the ScheduledTaskAction object to the $Sta variable. The second command creates a scheduled task trigger that starts every day at 3:00 A.M and assigns the ScheduledTaskTrigger object to the $Stt variable. The third command registers the scheduled task Task01 to run the task action named Cmd every day at 3:00 A.M.

Example 3: Register a scheduled task that starts every 3 days

PS C:\>$Sta = New-ScheduledTaskAction -Execute "Cmd"
PS C:\>$Stt = New-ScheduledTaskTrigger -Daily -DaysInterval 3 -At 3am
PS C:\>Register-ScheduledTask Task01 -Action $Sta -Trigger $Stt

This example registers a scheduled task that starts every 3 days.

The first command creates a scheduled task action named Cmd and assigns the ScheduledTaskAction object to the $Sta variable. The second command creates a scheduled task trigger that starts every 3 days at 3:00 A.M and assigns the ScheduledTaskTrigger object to the $Stt variable. The third command registers the scheduled task Task01 to run the task action named cmd every 3 days at 3:00 A.M.

Example 4: Register a scheduled task that starts every-other week

PS C:\>$Sta = New-ScheduledTaskAction -Execute "Cmd"
PS C:\>$Stt = New-ScheduledTaskTrigger -Weekly -WeeksInterval 2 -DaysOfWeek Sunday -At 3am
PS C:\>Register-ScheduledTask Task01 -Action $Sta -Trigger $Stt

This example registers a scheduled task that starts every other week.

The first command creates a scheduled task action named Cmd and assigns the ScheduledTaskAction object to the $Sta variable. The second command creates a scheduled task trigger that starts every other Sunday at 3:00 A.M and assigns the ScheduledTaskTrigger object to the $Stt variable. The third command registers the scheduled task Task01 to run the task action named Cmd every other Sunday at 3:00 A.M.

Example 5: Register a scheduled task that starts when a user logs on

PS C:\>$Sta = New-ScheduledTaskAction -Execute "Cmd"
PS C:\>$Stt = New-ScheduledTaskTrigger -AtLogon
PS C:\>Register-ScheduledTask Task01 -Action $Sta -Trigger $Stt

This example registers a scheduled task that starts when a user logs on.

The first command creates a scheduled task action named Cmd and assigns the ScheduledTaskAction object to the $Sta variable. The second command creates a scheduled task trigger that starts when a user logs on, and assigns the ScheduledTaskTrigger object to the $Stt variable. The third command registers the scheduled task Task01 to run the task action named Cmd when a user logs on.

Parameters

-AsJob

Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-At

Specifies a date and time to trigger the task. This parameter is valid for calendar-based triggers (Once, Daily, Weekly).

Type:DateTime
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-AtLogOn

Indicates that a trigger starts a task when a user logs on.

Type:SwitchParameter
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-AtStartup

Indicates that a trigger starts a task when the system is started.

Type:SwitchParameter
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CimSession

Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a Common Information Model (CIM) session object that represents a connection to a local computer or a remote computer, such as the output of a New-CimSession or Get-CimSession cmdlet. The default is the current session on the local computer.

Type:CimSession[]
Aliases:Session
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Daily

Indicates that a trigger starts a task on a recurring daily schedule.

Type:SwitchParameter
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-DaysInterval

Specifies the interval between the days in the schedule. An interval of 1 produces a daily schedule. An interval of 2 produces an every-other day schedule.

Type:UInt32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DaysOfWeek

Specifies an array of the days of the week on which Task Scheduler runs the task.

Type:DayOfWeek[]
Accepted values:Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Once

Indicates that a trigger starts a task once at a time specified in the At parameter.

Type:SwitchParameter
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-RandomDelay

Specifies a random amount of time to delay the start time of the trigger. The delay time is a random time between the time the task triggers and the time that you specify in this setting.

Type:TimeSpan
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RepetitionDuration

Specifies how long the repetition pattern repeats after the task starts.

Type:TimeSpan
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RepetitionInterval

Specifies an amount of time between each restart of the task. The task will run, wait for the time interval specified, and then run again. This cycle continues for the time that you specify for the RepetitionDuration parameter.

Type:TimeSpan
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ThrottleLimit

Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If this parameter is omitted or a value of 0 is entered, then Windows PowerShell® calculates an optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. The throttle limit applies only to the current cmdlet, not to the session or to the computer.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-User

Specifies the identifier of the user for a trigger that starts a task when a user logs on.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Weekly

Indicates that the trigger starts a task on a recurring weekly schedule.

Type:SwitchParameter
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-WeeksInterval

Specifies the interval between the weeks in the schedule. An interval of 1 produces a weekly schedule. An interval of 2 produces an every-other week schedule.

Type:UInt32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Outputs

CimInstance