PowerShell Logo Small

New-ScheduledTaskPrincipal



This is the built-in help made by Microsoft for the command 'New-ScheduledTaskPrincipal', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Creates an object that contains a scheduled task principal.

SYNTAX


New-ScheduledTaskPrincipal [-UserId] <String> [[-LogonType] <LogonTypeEnum>] [[-RunLevel] <RunLevelEnum>] [[-ProcessTokenSidType] <ProcessTokenSidTypeEnum>]
[[-RequiredPrivilege] <String[]>] [[-Id] <String>] [-AsJob] [-CimSession <CimSession[]>] [-ThrottleLimit <Int32>] [<CommonParameters>]
New-ScheduledTaskPrincipal [-GroupId] <String> [[-RunLevel] <RunLevelEnum>] [[-ProcessTokenSidType] <ProcessTokenSidTypeEnum>] [[-RequiredPrivilege] <String[]>] [[-Id]
<String>] [-AsJob] [-CimSession <CimSession[]>] [-ThrottleLimit <Int32>] [<CommonParameters>]



Search powershellhelp.space

DESCRIPTION


The New-ScheduledTaskPrincipal cmdlet creates an object that contains a scheduled task principal. Use a scheduled task principal to run a task under the security context of
a specified account. When you use a scheduled task principal, Task Scheduler can run the task regardless of whether that account is logged on.


You can use the definition of a scheduled task principal to register a new scheduled task or update an existing task registration.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/p/?linkid=287553
Register-ScheduledTask
Get-ScheduledTaskInfo
New-ScheduledTaskAction
New-ScheduledTaskSettingsSet
New-ScheduledTaskTrigger

REMARKS

<

Examples


Example 1: Register a scheduled task by using a user ID for a task principal

The first command creates a scheduled task action named Cmd and assigns the ScheduledTaskAction object to the Sta variable.
PS C:\>$Sta = New-ScheduledTaskAction -Execute "Cmd"

The second command creates a scheduled task principal. The New-ScheduledTaskPrincipal cmdlet specifies that Task Scheduler uses the Local Service account to run tasks, and
that the Local Service account uses the Service Account logon. The command assigns the ScheduledTaskPrincipal object to the STPrin variable.
PS C:\>$STPrin = New-ScheduledTaskPrincipal -UserId "LOCALSERVICE" -LogonType ServiceAccount

The third command registers the scheduled task Task01 to run the task action named Cmd. The Principal parameter specifies that the Task Scheduler uses the Local Service
account to run the task.
PS C:\>Register-ScheduledTask Task01 -Action $a -Principal $p



This example registers a scheduled task that will run as the Local Service account.




Example 2: Register a scheduled task by using a user group for a task principal

The first command creates a scheduled task action named cmd and assigns the ScheduledTaskAction object to the Sta variable.
PS C:\>$Sta = New-ScheduledTaskAction cmd

The second command creates a scheduled task principal. The New-ScheduledTaskPrincipal cmdlet specifies that Task Scheduler uses the Administrators user group that has the
highest privileges to run tasks. The command assigns the ScheduledTaskPrincipal object to the STPrin variable.
PS C:\>$STPrin = New-ScheduledTaskPrincipal -GroupId "BUILTIN\Administrators" -RunLevel Highest

The third command registers the scheduled task Task01 to run the task action named Cmd. The Principal parameter specifies that Task Scheduler uses the Administrators user
group to run the task.
PS C:\>Register-ScheduledTask Task01 -Action $Sta -Principal $STPrin



This example registers a scheduled task that runs under logged-in members of the Administrators user group that has the highest privileges.