TaskFolder.RegisterTask method

Article
12/11/2020

For scripting, registers (creates) a new task in the folder using XML to define the task.

Syntax

TaskFolder.RegisterTask( _
  ByVal path, _
  ByVal xmlText, _
  ByVal flags, _
  ByVal userId, _
  ByVal password, _
  ByVal logonType, _
  [ ByVal sddl ], _
  ByRef pTask _
)

Parameters

path [in]

The name of the task. If this value is Nothing, the task will be registered in the root task folder and the task name will be a GUID value that is created by the Task Scheduler service.

A task name cannot begin or end with a space character. The '.' character cannot be used to specify the current task folder and the '..' characters cannot be used to specify the parent task folder in the path.

xmlText [in]

An XML-formatted description of the task.

The following topics contain tasks defined using XML.

flags [in]

A TASK_CREATION constant.

Value	Meaning
TASK_VALIDATE_ONLY 0x1	The Task Scheduler checks the syntax of the XML that describes the task but does not register the task. This constant cannot be combined with the TASK_CREATE, TASK_UPDATE, or TASK_CREATE_OR_UPDATE values.
TASK_CREATE 0x2	The Task Scheduler registers the task as a new task.
TASK_UPDATE 0x4	The Task Scheduler registers the task as an updated version of an existing task. When a task with a registration trigger is updated, the task will execute after the update occurs.
TASK_CREATE_OR_UPDATE 0x6	The Task Scheduler either registers the task as a new task or as an updated version if the task already exists. Equivalent to TASK_CREATE \| TASK_UPDATE.
TASK_DISABLE 0x8	The Task Scheduler disables the existing task.
TASK_DONT_ADD_PRINCIPAL_ACE 0x10	The Task Scheduler is prevented from adding the allow access-control entry (ACE) for the context principal. When the TaskFolder.RegisterTask function is called with this flag to update a task, the Task Scheduler service does not add the ACE for the new context principal and does not remove the ACE from the old context principal.
TASK_IGNORE_REGISTRATION_TRIGGERS 0x20	The Task Scheduler creates the task, but ignores the registration triggers in the task. By ignoring the registration triggers, the task will not execute when it is registered unless a time-based trigger causes it to execute on registration.

userId [in]

The user credentials that are used to register the task.

Note

If the task is defined as a Task Scheduler 1.0 task, then do not use a group name (rather than a specific user name) in this userId parameter. A task is defined as a Task Scheduler 1.0 task when the version attribute of the Task element in the task's XML is set to 1.1.

password [in]

The password for the userId that is used to register the task. When the TASK_LOGON_SERVICE_ACCOUNT logon type is used, the password must be an empty VARIANT value such as VT_NULL or VT_EMPTY.

logonType [in]

Defines what logon technique is used to run the registered task.

Value	Meaning
TASK_LOGON_NONE 0	The logon method is not specified. Used for non-NT credentials.
TASK_LOGON_PASSWORD 1	Use a password for logging on the user. The password must be supplied at registration time.
TASK_LOGON_S4U 2	Use an existing interactive token to run a task. The user must log on using a service for user (S4U) logon. When an S4U logon is used, no password is stored by the system and there is no access to either the network or to encrypted files.
TASK_LOGON_INTERACTIVE_TOKEN 3	User must already be logged on. The task will be run only in an existing interactive session.
TASK_LOGON_GROUP 4	Group activation. The groupId field specifies the group.
TASK_LOGON_SERVICE_ACCOUNT 5	Indicates that a Local System, Local Service, or Network Service account is being used as a security context to run the task.
TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD 6	First use the interactive token. If the user is not logged on (no interactive token is available), then the password is used. The password must be specified when a task is registered. This flag is not recommended for new tasks because it is less reliable than TASK_LOGON_PASSWORD.

sddl [in, optional]

The security descriptor that is associated with the registered task. You can specify the access control list (ACL) in the security descriptor for a task in order to allow or deny certain users and groups access to a task.

Note

If the Local System account is denied access to a task, then the Task Scheduler service can produce unexpected results.

pTask [out]

A RegisteredTask object that represents the new task.

Return value

This method does not return a value.

Remarks

For a task, that contains a message box action, the message box will be displayed if the task is activated and the task has an interactive logon type. To set the task logon type to interactive, specify 3 (TASK_LOGON_INTERACTIVE_TOKEN) or 4 (TASK_LOGON_GROUP) in the LogonType property of the task principal, or in the logonType parameter of TaskFolder.RegisterTask or TaskFolder.RegisterTaskDefinition.

Only a member of the Administrators group can create a task with a boot trigger.

You can successfully register a task with a group specified in the userId parameter and 3 (TASK_LOGON_INTERACTIVE_TOKEN) specified in the logonType parameter of TaskFolder.RegisterTask or TaskFolder.RegisterTaskDefinition, but the task will not run.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Type library	Taskschd.tlb
DLL	Taskschd.dll