Install-ScheduledTask

Installs a scheduled task on the current computer.

Syntax

Install-ScheduledTask -Name <String> -TaskToRun <String> -OnEvent -EventChannelName <String> -EventXPathQuery <String> [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-Delay <TimeSpan>] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskToRun <String> -OnIdle <Int32> [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskToRun <String> -OnLogon [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-Delay <TimeSpan>] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskToRun <String> -OnStart [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-Delay <TimeSpan>] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskToRun <String> -Once [-StartDate <DateTime>] -StartTime <TimeSpan> [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskToRun <String> [-Month <Month[]>] -WeekOfMonth {First | Second | Third | Fourth | Last} -DayOfWeek <DayOfWeek[]> [-Interval <Int32>] [-StartDate <DateTime>] [-StartTime <TimeSpan>] [-Duration <TimeSpan>] [-EndDate <DateTime>] [-EndTime <TimeSpan>] [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskToRun <String> -LastDayOfMonth [-Month <Month[]>] [-Interval <Int32>] [-StartDate <DateTime>] [-StartTime <TimeSpan>] [-Duration <TimeSpan>] [-EndDate <DateTime>] [-EndTime <TimeSpan>] [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskToRun <String> -Month <Month[]> -DayOfMonth <Int32> [-Interval <Int32>] [-StartDate <DateTime>] [-StartTime <TimeSpan>] [-Duration <TimeSpan>] [-EndDate <DateTime>] [-EndTime <TimeSpan>] [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskToRun <String> -Monthly [-DayOfMonth <Int32>] [-Interval <Int32>] [-StartDate <DateTime>] [-StartTime <TimeSpan>] [-Duration <TimeSpan>] [-EndDate <DateTime>] [-EndTime <TimeSpan>] [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskToRun <String> -Weekly <Int32> [-DayOfWeek <DayOfWeek[]>] [-Interval <Int32>] [-StartDate <DateTime>] [-StartTime <TimeSpan>] [-Duration <TimeSpan>] [-EndDate <DateTime>] [-EndTime <TimeSpan>] [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskToRun <String> -Daily <Int32> [-Interval <Int32>] [-StartDate <DateTime>] [-StartTime <TimeSpan>] [-Duration <TimeSpan>] [-EndDate <DateTime>] [-EndTime <TimeSpan>] [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskToRun <String> -Hourly <Int32> [-StopAtEnd] [-StartDate <DateTime>] [-StartTime <TimeSpan>] [-Duration <TimeSpan>] [-EndDate <DateTime>] [-EndTime <TimeSpan>] [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskToRun <String> -Minute <Int32> [-StopAtEnd] [-StartDate <DateTime>] [-StartTime <TimeSpan>] [-Duration <TimeSpan>] [-EndDate <DateTime>] [-EndTime <TimeSpan>] [-Interactive] [-NoPassword] [-HighestAvailableRunLevel] [-TaskCredential <PSCredential>] [-Principal <String>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskXmlFilePath <String> [-TaskCredential <PSCredential>] [-Force] [<CommonParameters>]
Install-ScheduledTask -Name <String> -TaskXml <XmlDocument> [-TaskCredential <PSCredential>] [-Force] [<CommonParameters>]

Description

The Install-ScheduledTask function uses schtasks.exe to install a scheduled task on the current computer. If a task with the same name already exists, the existing task is left in place. Use the -Force switch to force Install-ScheduledTask to delete any existing tasks before installation.

If a new task is created, a Carbon.TaskScheduler.TaskInfo object is returned.

The schtasks.exe command line application is pretty limited in the kind of tasks it will create. If you need a scheduled task created with options not supported by Install-ScheduledTask, you can create an XML file using the Task Scheduler Schema or create a task with the Task Scheduler MMC then export that task as XML with the schtasks.exe /query /xml /tn <TaskName>. Pass the XML file (or the raw XML) with the TaskXmlFilePath or TaskXml parameters, respectively.

Related Commands

Parameters

Name Type Description Required? Pipeline Input Default Value
Name String

The name of the scheduled task to create. Paths are allowed to create tasks under folders.

true false
TaskToRun String

The task/program to execute, including arguments/parameters.

true false
Minute Int32

Create a scheduled task that runs every N minutes.

true false 0
Hourly Int32

Create a scheduled task that runs every N hours.

true false 0
StopAtEnd SwitchParameter

Stops the task at the EndTime or Duration if it is still running.

false false False
Daily Int32

Creates a scheduled task that runs every N days.

true false 0
Weekly Int32

Creates a scheduled task that runs every N weeks.

true false 0
Monthly SwitchParameter

Create a scheduled task that runs every month.

true false False
LastDayOfMonth SwitchParameter

Create a scheduled task that runs on the last day of every month. To run on specific months, specify the Month parameter.

true false False
Month Month[]

Create a scheduled task that runs on specific months. To create a monthly task, use the Monthly switch.

false false
DayOfMonth Int32

The day of the month to run a monthly task.

true false 0
WeekOfMonth WeekOfMonth

Create a scheduled task that runs a particular week of the month.

true false
DayOfWeek DayOfWeek[]

The day of the week to run the task. Default is today.

true false
Once SwitchParameter

Create a scheduled task that runs once.

true false False
OnStart SwitchParameter

Create a scheduled task that runs at startup.

true false False
OnLogon SwitchParameter

Create a scheduled task that runs when the user running the task logs on. Requires the TaskCredential parameter.

true false False
OnIdle Int32

Create a scheduled task that runs when the computer is idle for N minutes.

true false 0
OnEvent SwitchParameter

Create a scheduled task that runs when events appear in the Windows event log.

true false False
EventChannelName String

The name of the event channel to look at.

true false
EventXPathQuery String

The XPath event query to use to determine when to fire OnEvent tasks.

true false
TaskXmlFilePath String

Install the task from this XML path.

true false
TaskXml XmlDocument

Install the task from this XML.

true false
Interval Int32

Re-run the task every N minutes.

false false 0
StartDate DateTime

The date the task can start running.

false false
StartTime TimeSpan

The start time to run the task. Must be less than 24:00.

true false
Duration TimeSpan

The duration to run the task. Usually used with Interval to repeatedly run a task over a given time span. By default, re-runs for an hour. Can't be used with EndTime.

false false
EndDate DateTime

The last date the task should run.

false false
EndTime TimeSpan

The end time to run the task. Must be less than 24:00. Can't be used with Duration.

false false
Interactive SwitchParameter

Enables the task to run interactively only if the user is currently logged on at the time the job runs. The task will only run if the user is logged on. Must be used with TaskCredential parameter.

false false False
NoPassword SwitchParameter

No password is stored. The task runs non-interactively as the given user, who must be logged in. Only local resources are available. Must be used with TaskCredential parameter.

false false False
HighestAvailableRunLevel SwitchParameter

If the user is an administrator, runs the task with full administrator rights. The default is to run with limited administrative privileges.

If UAC is enabled, an administrator has two security tokens: a filtered token that gets used by default and grants standard user rights and a full token that grants administrative rights that is only used when a program is "Run as administrator". Using this switch runs the scheduled task with the adminisrators full token. (Information taken from How does "Run with the highest privileges" really work in Task Scheduler ?.)

false false False
Delay TimeSpan

The wait time to delay the running of the task after the trigger is fired. Must be less than 10,000 minutes (6 days, 22 hours, and 40 minutes).

false false
TaskCredential PSCredential

The principal the task should run as. Use Principal parameter to run as a built-in security principal. Required if Interactive or NoPassword switches are used.

false false
Principal String

The built-in identity to use. The default is System. Use the TaskCredential parameter to run as non-built-in security principal.

false false System
Force SwitchParameter

Create the task even if a task with the same name already exists (i.e. delete any task with the same name before installation).

false false False

Return Values

Carbon.TaskScheduler.TaskInfo.

EXAMPLE 1

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'C:\Windows\system32\notepad.exe' -Minute 5

Creates a scheduled task "CarbonSample" to run notepad.exe every five minutes. No credential or principal is provided, so the task will run as System.

EXAMPLE 2

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'C:\Windows\system32\notepad.exe' -Minute 1 -TaskCredential (Get-Credential 'runasuser')

Demonstrates how to run a task every minute as a specific user with the TaskCredential parameter.

EXAMPLE 3

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'C:\Windows\system32\notepad.exe' -Minute 1 -Principal LocalService

Demonstrates how to run a task every minute as a built-in principal, in this case Local Service.

EXAMPLE 4

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'calc.exe' -Minute 5 -StartTime '12:00' -EndTime '14:00' -StartDate '6/6/2006' -EndDate '6/6/2006'

Demonstrates how to run a task every 5 minutes between the given start date/time and end date/time. In this case, the task will run between noon and 2 pm on 6/6/2006.

EXAMPLE 5

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad' -Hourly 1

Creates a scheduled task CarbonSample which runs notepad.exe every hour as the LocalService user.

EXAMPLE 6

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -Weekly 1

Demonstrates how to run a task ever N weeks, in this case every week.

EXAMPLE 7

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -Monthly

Demonstrates how to run a task the 1st of every month.

EXAMPLE 8

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -Monthly -DayOfMonth 15

Demonstrates how to run a monthly task on a specific day of the month.

EXAMPLE 9

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -Month 1,4,7,10 -DayOfMonth 5

Demonstrates how to run a task on specific months of the year on a specific day of the month.

EXAMPLE 10

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -WeekOfMonth First -DayOfWeek Sunday

Demonstrates how to run a task on a specific week of each month. In this case, the task will run the first Sunday of every month.

EXAMPLE 11

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -Month 1,5,9 -WeekOfMonth First -DayOfWeek Sunday

Demonstrates how to run a task on a specific week of specific months. In this case, the task will run the first Sunday of January, May, and September.

EXAMPLE 12

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -LastDayOfMonth

Demonstrates how to run a task the last day of every month.

EXAMPLE 13

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -LastDayOfMonth -Month 1,6

Demonstrates how to run a task the last day of specific months. In this case, the task will run the last day of January and June.

EXAMPLE 14

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -Once -StartTime '0:00'

Demonstrates how to run a task once. In this case, the task will run at midnight of today (which means it probably won't run since it is always past midnight).

EXAMPLE 15

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -OnStart

Demonstrates how to run a task when the computer starts up.

EXAMPLE 16

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -OnStart -Delay '0:30'

Demonstrates how to run a task when the computer starts up after a certain amount of time passes. In this case, the task will run 30 minutes after the computer starts.

EXAMPLE 17

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -OnLogon -TaskCredential (Get-Credential 'runasuser')

Demonstrates how to run a task when the user running the task logs on. Usually you want to pass a credential when setting up a logon task, since the built-in users never log in.

EXAMPLE 18

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -OnLogon -Delay '1:45' -TaskCredential (Get-Credential 'runasuser')

Demonstrates how to run a task after a certain amount of time passes after a user logs in. In this case, the task will run after 1 hour and 45 minutes after runasuser logs in.

EXAMPLE 19

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -OnIdle

Demonstrates how to run a task when the computer is idle.

EXAMPLE 20

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -OnIdle -Delay '0:05'

Demonstrates how to run a task when the computer has been idle for a desired amount of time. In this case, the task will run after the computer has been idle for 5 minutes.

EXAMPLE 21

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'wevtvwr.msc' -OnEvent -EventChannelName System -EventXPathQuery '*[Sytem/EventID=101]'

Demonstrates how to run an event when certain events are written to the event log. In this case, wevtvwr.msc will run whenever an event with ID 101 is published in the System event channel.

EXAMPLE 22

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -TaskXmlFilePath $taskXmlPath

Demonstrates how to create a task using the Task Scheduler XML schema for a task that runs as a built-in principal. You can export task XML with the schtasks /query /xml /tn <Name> command.

EXAMPLE 23

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -TaskXmlFilePath $taskXmlPath -TaskCredential (Get-Credential 'runasuser')

Demonstrates how to create a task using the Task Scheduler XML schema for a task that will run as a specific user. The username in the XML file should match the username in the credential.

EXAMPLE 24

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -TaskXml $taskXml

Demonstrates how to create a task using raw XML that conforms to the Task Scheduler XML schema for a task that will run as a built-in principal. In this case, $taskXml should be an XML document.

EXAMPLE 25

Install-ScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -TaskXml $taskXml -TaskCredential (Get-Credential 'runasuser')

Demonstrates how to create a task using raw XML that conforms to the Task Scheduler XML schema for a task that will run as a specific user. In this case, $taskXml should be an XML document. The username in the XML document should match the username in the credential.

EXAMPLE 26

Install-ScheduledTask -Name 'CarbonTasks\CarbonSample' -TaskToRun 'notepad.exe' -Monthly

Demonstrates how to create tasks under a folder/directory: use a path for the Name parameter.