TaskFolderRegisterTaskDefinition(String, TaskDefinition, TaskCreation, String, String, TaskLogonType, String) Method

Registers (creates) a task in a specified location using a TaskDefinition instance to define a task.

Definition

Namespace: Microsoft.Win32.TaskScheduler
Assembly: Microsoft.Win32.TaskScheduler (in Microsoft.Win32.TaskScheduler.dll) Version: 2.11.0
C#View SourceRequest Example
public Task RegisterTaskDefinition(
	string path,
	TaskDefinition definition,
	TaskCreation createType,
	string userId,
	string password = null,
	TaskLogonType logonType = TaskLogonType.S4U,
	string sddl = null
)

Parameters

path  String
The task name. If this value is NULL, 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.
definition  TaskDefinition
The TaskDefinition of the registered task.
createType  TaskCreation
A union of TaskCreation flags.
userId  String
The user credentials used to register the task.
password  String  (Optional)
The password for the userId used to register the task.
logonType  TaskLogonType  (Optional)
A TaskLogonType value that defines what logon technique is used to run the registered task.
sddl  String  (Optional)
The security descriptor 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.

Return Value

Task
A Task instance that represents the new task. This will return null if createType is set to ValidateOnly and there are no validation errors.

Remarks

This method is effectively the "Save" method for tasks. It takes a modified TaskDefinition instance and registers it in the folder defined by this TaskFolder instance. Optionally, you can use this method to override the user, password and logon type defined in the definition and supply security against the task.

Example

This first example registers a simple task with a single trigger and action using the default security.

C#
// Create a new task definition for the local machine and assign properties
TaskDefinition td = TaskService.Instance.NewTask();
td.RegistrationInfo.Description = "Does something";

// Add a trigger that, starting tomorrow, will fire every other week on Monday and Saturday
td.Triggers.Add(new WeeklyTrigger(DaysOfTheWeek.Monday | DaysOfTheWeek.Saturday, 2));

// Create an action that will launch Notepad whenever the trigger fires
td.Actions.Add("notepad.exe", "c:\\test.log");

// Register the task in the root folder of the local machine using the current user and the S4U logon type
TaskService.Instance.RootFolder.RegisterTaskDefinition("Test", td);

This example registers that same task using the SYSTEM account.

C#
TaskService.Instance.RootFolder.RegisterTaskDefinition("TaskName", taskDefinition, TaskCreation.CreateOrUpdate, "SYSTEM", null, TaskLogonType.ServiceAccount);

This example registers that same task using a specific username and password along with a security definition.

C#
TaskService.Instance.RootFolder.RegisterTaskDefinition("TaskName", taskDefinition, TaskCreation.CreateOrUpdate, "userDomain\\userName", "userPassword", TaskLogonType.Password, @"O:BAG:DUD:(A;ID;0x1f019f;;;BA)(A;ID;0x1f019f;;;SY)(A;ID;FA;;;BA)(A;;FR;;;BU)");

Exceptions

ArgumentOutOfRangeException Task names may not include any characters which are invalid for file names. or Task names ending with a period followed by three or fewer characters cannot be retrieved due to a bug in the native library.
NotV1SupportedExceptionThis LogonType is not supported on Task Scheduler 1.0. or Security settings are not available on Task Scheduler 1.0. or Registration triggers are not available on Task Scheduler 1.0. or XML validation not available on Task Scheduler 1.0.

See Also