This is the built-in help made by Microsoft for the command 'New-ScheduledTaskPrincipal', in PowerShell version 3 - as retrieved from
Windows version 'Microsoft Windows Server 2012 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.
Creates an object that contains a scheduled task principal.
New-ScheduledTaskPrincipal [-UserId] <String> [[-LogonType] <LogonTypeEnum>] [[-RunLevel] <RunLevelEnum>] [[-ProcessTokenSidType]
<ProcessTokenSidTypeEnum>] [[-RequiredPrivilege] <String[]>] [[-Id] <String>] [-AsJob [<SwitchParameter>]] [-CimSession <CimSession[]>]
[-ThrottleLimit <Int32>] [<CommonParameters>]
New-ScheduledTaskPrincipal [-GroupId] <String> [[-RunLevel] <RunLevelEnum>] [[-ProcessTokenSidType] <ProcessTokenSidTypeEnum>]
[[-RequiredPrivilege] <String[]>] [[-Id] <String>] [-AsJob [<SwitchParameter>]] [-CimSession <CimSession[]>] [-ThrottleLimit <Int32>]
[<CommonParameters>]
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.
<
Register-ScheduledTask
Get-ScheduledTaskInfo
New-ScheduledTaskAction
New-ScheduledTaskSettingsSet
New-ScheduledTaskTrigger
<
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.