Creating a "brushed up" Task Scheduler UDF?

[water]

The Microsoft Windows Task Scheduler offers a lot of features. The two existing UDFs are a bit "complex" to use and miss help files and examples for each function.

Based on a discussion on the german forum we would like to create a new UDF based on the existing "template" UDFs.

• Which functions do you miss in the existing UDFs?
• Should there be more examples?
• Should there be a help file?
• Should there be a wiki entry explaining the concepts?
• Which functions should be made easier to use?
• What else?

Basic conditions

• Only Task Scheduler 2.0 will be supported (>= Windows Vista, Windows Server 2008).
• The UDF will use COM; neither AT.exe nor SCHTASKS.exe will be used.
• It will support as many of the objects and parameters as sensible.
• The UDF should be useable for everyone (beginners and experts) to suit their needs.

Completed functions (fully documented including examples) - last changed: 2019-12-03

Spoiler

• _TS_Open: Create Task Scheduler object and connect to the Task Scheduler Service - even on another device.
• _TS_Close: Close the Connection and do some cleanup.
• _TS_ErrorNotify: COM error handling.
• _TS_ErrorText: Returns the full error message text for an error number.
• _TS_ActionCreate: Create a new Action object for an existing Task or a Task Definition.
• _TS_ActionDelete: Delete a single or all Action objects by ID or index.
• _TS_FolderCreate: Create a Folder where to store Tasks.
• _TS_FolderDelete: Delete a task Folder.
• _TS_FolderExists: Check if a Task Folder exists.
• _TS_FolderGet: Returns the object of a Task Folder.
• _TS_RunningTaskList: Returns a list of all currently running Tasks.
• _TS_TaskCopy: Copy a Task with the same or a new name to the same or a different Task Folder.
• _TS_TaskCreate: Create a new Task.
• _TS_TaskDelete: Delete a Task.
• _TS_TaskExists: Checks if a Task exists.
• _TS_TaskExportXML: Export the XML definition of a Task to a file or an array/string.
• _TS_TaskGet: Retrieve the object of a single Task.
• _TS_TaskImportXML: Import the XML definition of a Task from a file or an array/string and create a Task with the same/different name in the same or a different Task Folder.
• _TS_TaskList: Get a list of Tasks in a Task Folder.
• _TS_TaskPropertiesGet: Extract all Properties of a Task and return them in different formats.
• _TS_TaskPropertiesSet: Sets the properties of the following Tasks Objects: Definition, Principal, RegistrationInfo, Settings, IdleSettings and NetworkSettings.
• _TS_TaskRegister: Register the Task Definition to finish the Task creation process.
• _TS_TaskRun: Run the Registered Task immediately.
• _TS_TaskStop: Stops all instances of the Registered Task immediately.
• _TS_TaskUpdate: Update a Task (you can use _TS_TaskRegister as well).
• _TS_TriggerCreate: Create a trigger object for a task.
• _TS_TriggerDelete: Delete a single or all Trigger objects by ID or index.
• _TS_VersionInfo: Returns an array of information about the UDF.
• _TS_Wrapper_ActionCreate: Wrapper to create the actions to be executed when the task runs.
• _TS_Wrapper_PrincipalSet: Wrapper to set the Principal properties of a Task Definition object.
• _TS_Wrapper_TaskCreate: Wrapper to create a Task Definition object so you can then set all needed properties using other Wrapper functions.
• _TS_Wrapper_TaskRegister: Wrapper to register a task .
• _TS_Wrapper_TriggerDateTime: Wrapper to create a date/time based Trigger.
• _TS_Wrapper_TriggerLogon: Wrapper to create a logon trigger.

Planned functions (functions we are working on) - last changed: 2019-10-25

Spoiler

• _TS_TaskValidate: Check all objects of the Task Definition plus the Task Definition as a whole to be valid. Errors, warnings etc. will be returned in an array.

Suggested functions (we need to discuss if they schould be implemented) - last changed: 2025-01-25

Spoiler

• Functions for "Easy" tasks: Suggested here Done by providing wrapper functions
• Functions to import/export tasks as XML. Suggested here Done
• Create Examples/functions to mimic some basic tasks. Suggested here Done - for details please see the following spoiler

Spoiler

        * Starting an Executable at a Specific Time: Done - _TS_Wrapper_TaskCreate.au3 - Example 4
        * Starting an Executable Daily: Done - _TS_Wrapper_TaskCreate.au3 - Example 2
        * Starting an Executable on System Boot: Done - No Wrapper and no Example provided!
        * Starting an Executable Weekly: Done - _TS_Wrapper_TaskCreate.au3 - Example 3
        * Starting an Executable When a Task is Registered: Done - No Wrapper and no Example provided!
        * Starting an Executable When a User Logs On: Done - _TS_Wrapper_TaskCreate.au3 - Example 1
        * Enumerating Tasks and Displaying Task Information: _TS_TaskList.au3

• _TS_TaskRunWait: Define a task and wait until it has run. Suggested here Rejected. Starting the program from your script or checking the status of the task in a loop seems more sensible.
• _TS_TaskStatusGet: Get all Status flags of a task with a single call (enabled, started, hidden ...). Suggested by water Rejected. Can be achieved with _TS_TaskPropertiesGet as well

Postponed functions (we will discuss this functions when the need arises) - last changed: 2019-09-30

Spoiler

• None

Edited January 25 by water
Fixed the "Suggested Functions" section. ALL Triggers are supported by the UDF but I do not provide an Example for every Trigger.

[FrancescoDiMuro]

@water

Could you please post the links of these UDFs?

Thanks

[Musashi]

@FrancescoDiMuro

https://www.autoitscript.com/forum/index.php?showtopic=135994

https://www.autoitscript.com/forum/index.php?showtopic=83355

Edit :

Quote

Based on a discussion on the german forum we would like to create a new UDF based on the existing "template" UDFs.

You will find the discussion under : https://autoit.de/index.php?thread/86586-windows-aufgabenplanung-per-schtasks-exe-einen-task-erstellen-und-abfragen/&pageNo=1

BTW : After years of reading, this is my first post here 🙂.

 

Edit 2 : @FrancescoDiMuro

Thank you for your friendly welcome. I'm editing this in my post here because I don't want to disturb the main thread .

Greetings Musashi

Edited August 25, 2019 by Musashi

[water]

This links can be found in the wiki as well: https://www.autoitscript.com/wiki/User_Defined_Functions#Windows

• Taskplanner/Taskscheduler COM (by Allow2010) - an UDF for using the Windows Taskplaner / Task Scheduler.
• Task Scheduler (by dbzfanatic) - Task Scheduler UDF.

[FrancescoDiMuro]

@Musashi, @water

Thanks for the links!

38 minutes ago, Musashi said:

BTW : After years of reading, this is my first post here 🙂.

Welcome actively in this wonderful community! 

EDIT:
@water
The UDF by Allow2010 is more complete and already uses objects, so, it could be a point from where to start the new UDF.
So, just wait for others for votes

Edited August 25, 2019 by FrancescoDiMuro

[water]

That's what we intend to do because the other UDF uses Sc.exe and is a few years older.

[seadoggie01]

I think that you should consider having functions that create the task object and have users use functions to edit the task object's properties before finally registering it... Maybe something like this:

;"Create the task"
Local $oTask = _Task_Create()
;"Schedule the task for once every day at 5pm"
_Task_ScheduleDaily($oTask, 17)
;"Run asap if missed"
_Task_RunIfMissed($oTask, True)
;"Register the task"
_Task_Register($oTask)

Edit: I suggest this to avoid having a HUGE param list like in Allow2010's... though he did a really nice job, his function is just ugly

Edited August 25, 2019 by seadoggie01

[mLipok]

I would like to fully compatibility with Au3Check and Au3Stripper.

[water]

6 hours ago, FrancescoDiMuro said:

The UDF by Allow2010 is more complete and already uses objects, so, it could be a point from where to start the new UDF.

I will add requirements from the posts to thread #1 so we have everthing at a single place.

[water]

1 hour ago, seadoggie01 said:

I think that you should consider having functions that create the task object and have users use functions to edit the task object's properties before finally registering it

There will be a function to set/modify all properties of a task. To limit parameters you will be able to group them (as MS did with properties grouped for Task, Definition, Actions, Principal, Registration, Settings, Triggers) and pass them as arrays to the task create or the task modify function.
There will be wrapper functions available for simple tasks. You pass a few parameters to this wrappers and they do all the work for you in the background.

I intend to create a function that retrieves all properties from a task and returns it the way the task create function expects them.
This means:

• You could create and test a task using the task management GUI provided by Microsoft
• extract the properties from this template using the UDF function
• do the needed modification and then
• copy the result to your script.

Comments?

[FrancescoDiMuro]

1 hour ago, water said:

Comments?

Well, you said almost everything about the new functionalities of the UDF and they would be just amazing!

Maybe write down a list of functions, and a short explanation of what they should/could do.

In this case, people can comment and you can get more "inspiration" for the UDF

Edited August 25, 2019 by FrancescoDiMuro

[AdamUL]

It would also be nice to have functions to import and export XML files of tasks.  I started writing a wrapper for the command line way to do it.  I'm not sure if it can be done with COM.  I've also just started working on updating Allow2010's UDF.  

Edit: Sounds like this is already mentioned in your plan.

Adam

Edited August 25, 2019 by AdamUL

[water]

At least export of the XML with COM is easy. And already on its way with function TaskPropertiesGet.

[mLipok]

How you plan to maintain COM Error Handler in this UDF?

[mLipok]

It would be good if examples will show the same problems as here:
https://docs.microsoft.com/pl-pl/windows/win32/taskschd/using-the-task-scheduler

of course, using this UDF.

 

Edited August 26, 2019 by mLipok

[water]

27 minutes ago, mLipok said:

How you plan to maintain COM Error Handler in this UDF?

The same way as in OutlookEx and all my other UDFs. I want to spend my time working on the UDF, not on handling COM errors. 

This has worked quite well since Jon changed the COM error handling the last time. 

[water]

I posted the first ALPHA for you to play with in the download section.
Have fun!

[mLipok]

Is this necessary to declare $oFolder in this following case:

Func _TS_FolderExists($oService, $sFolder)
    Local $oFolder = $oService.GetFolder($sFolder)
    If @error Then Return 0
    Return 1
EndFunc   ;==>_TS_FolderExists

 

?

[mLipok]

Few proposals for Au3Check compatibility

 

TaskScheduler.au3

[water]

No. Can be stripped down down to

$oService.GetFolder($sFolder)

But I'm sure we will make a beauty queen of this UDF at the end of the development