Tasks

You are reading our Automation1 API documentation for the .NET programming language.

In the .NET API, Tasks lets you interact with and manage Automation1 controller tasks.

The Basics

Each Automation1 controller has one or more tasks that execute AeroScript programs and AeroScript commands on the controller. Each task has a task name and a task index. Task indices start at 1. Task index 0 is reserved and cannot be used.

How to Use

In the .NET API, Tasks is part of the Controller.Runtime property. For all the APIs that operate under this property, the Automation1 controller must be running before you can do work with tasks. For more information about this property, see the Controller page.

To work with tasks in the .NET API, use the Controller.Runtime.Tasks property and index the task that you want to work with. A task can be specified by either task name or task index.

Refer to the example that follows.

Copy

controller.Runtime.Tasks[string taskName]
controller.Runtime.Tasks[int taskIndex]

You can get the status of a task to see if the task is running an AeroScript program or if there is an error on the task. Refer to the example that follows.

Copy

ControllerTaskStatus controllerTaskStatus = controller.Runtime.Tasks[string taskName].Status;

Each time that you access the Status property, you get a new status from the controller. For best results, access the Status property one time only to get the most current status. Then use the returned ControllerTaskStatus object until you need to get the most current status of the controller again. If you do not do this and try to access the Status property too many times, bugs known as race conditions can occur. These bugs occur when the status of the task changes between multiple accesses of the property.

Manage AeroScript Programs

You can use tasks in the .NET API to run AeroScript programs on controller tasks. This is one of two ways to command your Automation1 controller, with the other being Commands. Use the Program property on a task to manage AeroScript programs on the controller task. Refer to the example that follows.

Copy

controller.Runtime.Tasks[string taskName].Program.Run(string controllerFileName);

The Run method starts the execution of the AeroScript program, but it does not wait for the program to complete. The specified controller file can be either an AeroScript source file (.ascript) or a compiled AeroScript file (.a1exe). If the controller file is an AeroScript source file, then the file will be compiled before it is executed.

You can also specify a CompiledAeroScript object that you got from compiling AeroScript source with the Controller.Compiler property. See the Compiler page.

To determine if an AeroScript program is still running, get the task’s status. Then examine the TaskState property that returns the TaskState enum. The TaskState.ProgramRunning enum value will tell you if an AeroScript program is currently running on that task. The TaskState.ProgramComplete enum value will tell you if an AeroScript program completed successfully on that task. The TaskState.Error enum value will tell you if an AeroScript program failed with some type of error that you can examine with the Error property. Refer to the example that follows.

Copy

TaskState taskState = controller.Runtime.Tasks[string taskName].Status.TaskState;
ErrorInformation errorInformation = controller.Runtime.Tasks[string taskName].Error;

To stop an AeroScript program that is running, use the Stop method. Refer to the example that follows.

Copy

controller.Runtime.Tasks[string taskName].Program.Stop();

Handle AeroScript Application Messages

AeroScript programs that run on a controller task can use the AppMessage AeroScript functions to send information to a .NET custom application. Automation1 Studio also handles these AeroScript functions so you cannot use your custom application and Studio at the same time if you handle any AppMessage functions. To learn more, see the Application Message Functions page.

You can register for any of the AppMessage AeroScript functions with the AppMessage property. Each of the different AppMessage functions has its own property. When you register a handler for an AppMessage function, you must specify a delegate to a .NET method that will be invoked when the AppMessage AeroScript function is executed. Some AppMessage functions require a value to be returned to AeroScript, so your delegate will have to return a value too. You can register each AppMessage one time only. To change the registration of the AppMessage function, unregister the first handler. Then register the new second handler. Refer to the example that follows.

Copy

controller.Runtime.Tasks[string taskName].AppMessage.Box.Register(Func<AppMessageBoxArguments, int> handler);
controller.Runtime.Tasks[string taskName].AppMessage.Box.Unregister();
 
controller.Runtime.Tasks[string taskName].AppMessage.Display.Register(Action<AppMessageDisplayArguments> handler);
controller.Runtime.Tasks[string taskName].AppMessage.Display.Unregister();

Handle AeroScript Callbacks

AeroScript programs that run on a controller task can use the Callback() AeroScript function to send information to or to pass execution to a .NET custom application. When the Callback() function is executed from AeroScript, program execution on that task waits for any registered .NET callback handler to execute. The AeroScript program continues when the .NET callback handler completes. Each callback is identified by a unique identifier, which is a callback ID. This ID is used when you register for the callback and when you execute the Callback() AeroScript function. These handlers can be given data from AeroScript and return data back to AeroScript. To learn more, see the Callback Functions page.

Inputs into a .NET callback handler and outputs out of a .NET callback handler can be AeroScript integers, AeroScript reals, and AeroScript strings. AeroScript integers are 64-bit. They are represented in .NET by the long data type. AeroScript reals are double-precision floating-point numbers. They are represented in .NET by the double data type.

You can register for the Callback() AeroScript function with the Callback property. When you register a handler for the Callback() function, you must specify a delegate to a .NET method that will be invoked when the Callback() function is executed. The Callback() function requires values to be returned to AeroScript. Thus your delegate will have to return a value too. If you do not want to return any values, return empty arrays. You can register the Callback() function one time only. To change the registration of the Callback, unregister the first handler. Then register the new second handler. Refer to the example that follows.

Copy

controller.Runtime.Tasks[string taskName].Callback.Register(int callbackId, Func<ControllerTaskCallbackArguments, ControllerTaskCallbackReturn> handler);
controller.Runtime.Tasks[string taskName].Callback.Unregister(int callbackId);

Task Variables

In the .NET API, Task Variables lets you get and set task variables on a task on an Automation1 controller. You can use task variables to share information between iterations of a program running on the same task.

IMPORTANT: Task Variables are not under Tasks and are not accessible with the Controller.Runtime.Tasks property. Refer to Task Variables to learn how to use Task variables in the .NET API.

Thread Safety

All the methods and properties that operate under the Controller.Runtime.Tasks property are thread safe. You can call them from two or more threads without interference.

But because the .NET API is thread safe, that does not mean the controller can handle the operations. A single controller task can run only one AeroScript program at a time. You must synchronize or coordinate your process to prevent controller errors from occurring.

For Example

You can make a single .NET thread responsible for a single controller task.

Full Reference

For more information about the properties and methods that are available for Tasks, refer to the lists that follow.

Controller.Runtime.Tasks Properties

Controller.Runtime.Tasks[].AppMessage Methods

Controller.Runtime.Tasks[].Callback Methods

Controller.Runtime.Tasks[].Debug Methods

Controller.Runtime.Tasks[].Program Methods

ControllerRuntime.Tasks[].Motion Methods

ControllerTaskStatus Properties