TaskFolder.RegisterTask method
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 |
|
| DLL |
|