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 {January | February | March | April | May | June | July | August | September | October | November | December}] -WeekOfMonth {First | Second | Third | Fourth | Last} -DayOfWeek {Sunday | Monday | Tuesday | Wednesday | Thursday | Friday | Saturday} [-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 {January | February | March | April | May | June | July | August | September | October | November | December}] [-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 {January | February | March | April | May | June | July | August | September | October | November | December} -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 {Sunday | Monday | Tuesday | Wednesday | Thursday | Friday | Saturday}] [-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.