Командлет New-ScheduledTaskPrincipal

New-ScheduledTaskPrincipal — это командлет оболочки Windows PowerShell, предназначенный для создания объекта, представляющего учётную запись пользователя, от имени которой будет выполняться задание в планировщике задач Windows. Командлет входит в состав модуля ScheduledTasks, который предоставляет интерфейс для управления планировщиком задач через PowerShell. Результатом работы командлета является объект типа Microsoft.Management.Infrastructure.CimInstance#MSFT_TaskPrincipal, который затем передаётся другим командлетам (например, Register-ScheduledTask или Set-ScheduledTask) для назначения учётной записи конкретному заданию.

Синтаксис и параметры

Командлет имеет следующий формальный синтаксис (в упрощённом виде):

``powershell New-ScheduledTaskPrincipal [-UserID] <String> [[-LogonType] <String>] [[-RunLevel] <String>] [<CommonParameters>] ``

Основные параметры командлета:

• -UserID (обязательный) — строка, указывающая имя учётной записи пользователя в формате Домен\Имя_пользователя или Имя_компьютера\Имя_пользователя. Для встроенных учётных записей можно использовать значения NT AUTHORITY\SYSTEM, NT AUTHORITY\LOCALSERVICE, NT AUTHORITY\NETWORKSERVICE или BUILTIN\Administrators. Параметр принимает также имя пользователя без домена, если задание выполняется на локальной машине.
• -LogonType (необязательный) — строка, определяющая способ входа пользователя в систему при запуске задания. Допустимые значения:
• S4U — используется для заданий, не требующих интерактивного входа; пароль не запрашивается, но учётная запись должна иметь доступ к сетевым ресурсам.
• Password — задание запускается с использованием пароля, который должен быть передан при регистрации задания.
• InteractiveToken — задание выполняется в контексте текущего интерактивного пользователя (требуется, чтобы пользователь был залогинен).
• ServiceAccount — используется для служб; учётная запись должна быть настроена как служба.
• InteractiveOrPassword — задание может выполняться как при интерактивном входе, так и с паролем.
• По умолчанию используется S4U.
• -RunLevel (необязательный) — строка, определяющая уровень привилегий, с которым запускается задание. Допустимые значения:
• Limited — задание выполняется с правами обычного пользователя.
• HighestAvailable — задание выполняется с максимально доступными правами для данной учётной записи (например, для администратора — с полными правами).
• По умолчанию используется Limited.
• -Id (необязательный) — строка, задающая произвольный идентификатор для объекта учётной записи. Используется редко, в основном для внутренних целей.
• -DisplayName (необязательный) — строка, задающая отображаемое имя учётной записи. Не влияет на выполнение задания, служит для удобства.

Возвращаемый объект

Командлет возвращает объект CimInstance типа MSFT_TaskPrincipal, который содержит следующие свойства (все доступны только для чтения после создания):

• UserId — имя учётной записи.
• LogonType — тип входа.
• RunLevel — уровень привилегий.
• Id — идентификатор (если задан).
• DisplayName — отображаемое имя (если задано).

Этот объект не является самостоятельным заданием и не взаимодействует напрямую с планировщиком задач. Он используется как составная часть более крупного объекта — описания задания (CimInstance типа MSFT_TaskDefinition), которое затем передаётся командлетам Register-ScheduledTask или Set-ScheduledTask.

Примеры использования

Пример 1: Создание учётной записи для задания от имени системы

``powershell $principal = New-ScheduledTaskPrincipal -UserID "NT AUTHORITY\SYSTEM" -LogonType ServiceAccount -RunLevel HighestAvailable ``

Этот пример создаёт объект учётной записи для задания, которое будет выполняться от имени встроенной учётной записи SYSTEM с максимальными привилегиями.

Пример 2: Создание учётной записи для задания от имени конкретного пользователя

``powershell $principal = New-ScheduledTaskPrincipal -UserID "DOMAIN\Username" -LogonType Password -RunLevel Limited ``

Здесь создаётся объект для задания, которое будет запускаться от имени пользователя DOMAIN\Username. При регистрации задания потребуется указать пароль.

Пример 3: Использование в составе полного скрипта создания задания

``powershell $action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-File C:\Scripts\backup.ps1" $trigger = New-ScheduledTaskTrigger -Daily -At 3am $principal = New-ScheduledTaskPrincipal -UserID "NT AUTHORITY\SYSTEM" -LogonType ServiceAccount -RunLevel HighestAvailable $settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries Register-ScheduledTask -TaskName "DailyBackup" -Action $action -Trigger $trigger -Principal $principal -Settings $settings ``

В этом примере создаётся полное задание для ежедневного запуска скрипта PowerShell от имени системы.

Ограничения и особенности

• Командлет не проверяет существование указанной учётной записи на момент создания объекта. Ошибка может возникнуть только при попытке зарегистрировать задание с несуществующим пользователем.
• Для использования -LogonType Password необходимо при регистрации задания передать пароль через параметр -Password командлета Register-ScheduledTask. Если пароль не указан, задание может не запуститься.
• Командлет доступен только в Windows PowerShell (версии 3.0 и выше) и не входит в состав PowerShell Core (версии 6+), если не установлен модуль ScheduledTasks для Windows. В PowerShell 7 на Windows модуль ScheduledTasks доступен, но может требовать явного импорта.
• Для работы с командлетом требуются права администратора на локальной машине, если задание регистрируется для выполнения от имени другого пользователя или с повышенными привилегиями.

Связанные командлеты

• Get-ScheduledTask — получение списка зарегистрированных заданий.
• Register-ScheduledTask — регистрация нового задания в планировщике задач.
• Set-ScheduledTask — изменение параметров существующего задания.
• New-ScheduledTaskAction — создание действия для задания.
• New-ScheduledTaskTrigger — создание триггера для задания.
• New-ScheduledTaskSettingsSet — создание набора параметров выполнения задания.

Источники

• Документация Microsoft по командлету New-ScheduledTaskPrincipal (ScheduledTasks Module)
• Справка Windows PowerShell (Get-Help New-ScheduledTaskPrincipal -Detailed)
• Официальная документация по планировщику задач Windows (Task Scheduler)