The Register-ScheduledTask cmdlet registers a scheduled task definition on a local computer.
You can register a task to run executable files (.exe and .com), batch files (.bat and .cmd),
or any registered file type. However, this cmdlet does not check whether the file you intend it to
run is compatible with your version, edition, or platform specialization of Windows.
In this example, the set of commands uses cmdlets and variables to define and register a scheduled task.
The first command uses the New-ScheduledTaskTrigger cmdlet to assign a time trigger to the $Time variable.
The second command assigns the $User variable the name of the user account in the context of which
the task runs (Contoso\Administrator).
The third command assigns the $PS variable to PowerShell.exe.
This variable is used to define a task action.
The fourth command registers a scheduled task that is named SoftwareScan in the root folder.
The registered task uses the pre-created action and trigger values that are specified by the $Action and $User variables.
Parameters
-Action
Specifies an array of one or more work items for the task to run.
If you specify multiple actions, the computer runs them in order.
You can specify up to 32 actions.
Parameter properties
Type:
CimInstance[]
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
User
Position:
2
Mandatory:
True
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
Principal
Position:
2
Mandatory:
True
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-AsJob
Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete.
Parameter properties
Type:
SwitchParameter
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
(All)
Position:
Named
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-CimSession
Runs the cmdlet in a remote session or on a remote computer.
Enter a computer name or a session object, such as the output of a New-CimSession or Get-CimSession cmdlet.
The default is the current session on the local computer.
Parameter properties
Type:
CimSession[]
Default value:
None
Supports wildcards:
False
DontShow:
False
Aliases:
Session
Parameter sets
(All)
Position:
Named
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-Description
Briefly describes the task.
Parameter properties
Type:
String
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
User
Position:
8
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
Principal
Position:
8
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-Force
Instructs the cmdlet to perform the operation without prompting for confirmation.
Parameter properties
Type:
SwitchParameter
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
(All)
Position:
Named
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-InputObject
Specifies the input object that is used in a pipeline command.
Parameter properties
Type:
CimInstance
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
Object
Position:
2
Mandatory:
True
Value from pipeline:
True
Value from pipeline by property name:
False
Value from remaining arguments:
False
-Password
Specifies a password for the user account in the context of which the task runs.
The password is ignored for the well-known system accounts.
Well-known accounts are: NT AUTHORITY\SYSTEM, NT AUTHORITY\LOCALSERVICE, NT AUTHORITY\NETWORKSERVICE, and the well-known security identifiers (SIDs) for all three accounts.
Parameter properties
Type:
String
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
User
Position:
4
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
Xml
Position:
4
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
Object
Position:
4
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-Principal
Specifies the security context in which a task is run.
Parameter properties
Type:
CimInstance
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
Principal
Position:
5
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-RunLevel
Specifies the required privilege level to run tasks that are associated with the principal.
Parameter properties
Type:
RunLevelEnum
Default value:
None
Accepted values:
Limited, Highest
Supports wildcards:
False
DontShow:
False
Parameter sets
User
Position:
7
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-Settings
Specifies a configuration that the Task Scheduler service uses to determine how to run a task.
Parameter properties
Type:
CimInstance
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
User
Position:
4
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
Principal
Position:
4
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-TaskName
Specifies the name of a scheduled task.
Parameter properties
Type:
String
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
User
Position:
0
Mandatory:
True
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
Xml
Position:
0
Mandatory:
True
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
Principal
Position:
0
Mandatory:
True
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-TaskPath
Specifies an array of one or more paths for scheduled tasks in Task Scheduler namespace. You can use "*" for a wildcard character query.
You can use \* for the root folder. To specify a full TaskPath you need to include the leading and trailing \.
If you do not specify a path, the cmdlet uses the root folder.
Parameter properties
Type:
String
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
(All)
Position:
1
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
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.
Parameter properties
Type:
Int32
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
(All)
Position:
Named
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-Trigger
Specifies an array of one or more trigger objects that start a scheduled task.
A task can have a maximum of 48 triggers.
Parameter properties
Type:
CimInstance[]
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
User
Position:
3
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
Principal
Position:
3
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-User
Specifies the name of the user account in the context of which Windows runs the task.
Parameter properties
Type:
String
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
User
Position:
3
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
Xml
Position:
3
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
Object
Position:
3
Mandatory:
False
Value from pipeline:
False
Value from pipeline by property name:
False
Value from remaining arguments:
False
-Xml
Specifies the XML string that contains a task definition.
Parameter properties
Type:
String
Default value:
None
Supports wildcards:
False
DontShow:
False
Parameter sets
Xml
Position:
2
Mandatory:
True
Value from pipeline:
True
Value from pipeline by property name:
False
Value from remaining arguments:
False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable,
-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see
about_CommonParameters.