minute read

On this API page:

.NET API Guidelines

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

This page tells you about the guidelines that you must follow to correctly use the .NET API. It also includes information that is important to know when you start to write a large-scale custom application that uses the .NET API.

IMPORTANT: Before you read these guidelines, make sure that you read the About the .NET API page first. This page builds on that information.

The Three Controller Categories: Axis, Task, and System

The Automation1 controller is divided into three categories: axis, task, and system.

Each Automation1 controller has a fixed number of axes - 32 axes for a PC-based controller and 12 axes for a drive-based controller. The axis category consists of these axes and their configuration, parameters, and status.

Each Automation1 controller also has some number of controller tasks. The tasks can be different based on the type of controller and your license key. The task category consists of these controller tasks and their configuration, parameters, and status.

The system category consists of the Automation1 controller and its configuration, parameters, and status.

These three categories are important in the .NET API because different types of information are available for each one. For example, controller parameters, status, and data collection are all divided into these categories. Each class has three different properties, one for each category:

Axis property - A collection that is indexed by an axis name or an axis index.
Task property - A collection that is indexed by a task name or a task index.
System property - The Automation1 controller is the only system. The System property does not require you to specify a system from which to get or set the parameters.

If you must specify an axis, you can use the axis name or the axis index through method or property overloads.

If you must specify a task, you can use the task name or the task index through method or property overloads.

Errors and Exception Handling

The .NET API uses Microsoft's Design Guidelines for Exceptions. For all error conditions, exceptions will occur. For function argument validation, ArgumentException, ArgumentNullException, and ArgumentOutOfRangeException will occur.

The .NET API also defines its exception types. Most .NET API exceptions inherit from the ControllerException class. This class is used for all errors that are caused by the Automation1 controller. ControllerException is never thrown. But one of its inherited classes is thrown for specific error cases. Refer to the table that follows.

Inherited ControllerException Class	Description

ControllerArgumentException	The exception that is thrown when an argument to an Automation1 function or command is not valid.
ControllerOperationException	The exception that is thrown when a function or command cannot execute.
ControllerAxisAbortException	The exception that is thrown when an axis abort occurs during the execution of a command.
ControllerAxisFaultException	The exception that is thrown when the controller generates an axis fault during the execution of a command.
ControllerStateException	The exception that is thrown when a function or command cannot execute because the controller is not in the expected state, such as stopped, running, or resetting.
ControllerCommunicationException	The exception that is thrown when there is a problem communicating with the controller.
ControllerDisconnectedException	The exception that is thrown when you are no longer connected to the controller.

Axis Faults and Task Errors

.NET API exceptions are different from axis faults and controller task errors. An exception is thrown when an error occurs. The exception represents an error in one moment in time.

But axis faults and task errors are continuous error conditions that exist on an axis or a controller task.

For Example

If an axis moves into its end-of-travel limit, it will generate an end-of-travel limit axis fault. This axis fault stays until you acknowledge it.

If an AeroScript program divides by zero, it will cause a task error to occur on the task it was running. This task error stays until you stop the program.

An axis fault or a controller task might cause an exception to be thrown.

For Example

If you execute motion on an axis and that motion causes the controller to generate an axis fault, a .NET exception will be thrown.

If you execute an AeroScript command that causes a task error, a .NET API exception will also be thrown.

In these examples, the continuous axis fault or continuous task error caused an exception to be thrown. The fault or error continues to stay after you handle the exception.

To get active axis faults and controller task errors, use Status.

Match the .NET API Version with the Automation1 Controller Version

The version of the .NET API that you use in your custom application must match the version of the Automation1 controller that you are connecting to.

For Example

If you want to connect to an Automation1 controller that is running version 2.2.0, then your custom application must reference and use version 2.2.0 of the .NET API.

Upgrade the .NET API Version for Your Custom Application

To change the version of the .NET API that you are using, do the steps that follow:

Replace all the current .NET API DLL files with the new DLL files from the Automation1 version to which you are upgrading.
Recompile your custom application to reference the new versions of these DLL files.

You must recompile your custom application because the .NET DLL files are strong-named assemblies. Thus the exact version of the assembly that was referenced at compile-time must be used at run-time. The .NET runtime requires this.

For minor software versions, source compatibility and binary compatibility are preserved in the .NET API. But major software versions, such as 2.0.0, 3.0.0, or 4.0.0, might contain source compatibility or binary compatibility changes. The release notes for each software version will tell you if there are compatibility changes.

IMPORTANT: If one or more compatibility changes occur, you must update your custom application code with the new .NET API changes.

Distribute Your Custom Application

To get access to the .NET API, you must install Automation1-MDK on a Microsoft Windows PC. After you build your custom application, you can distribute and run it to any supported operating system. For information about which operating systems are supported, see Supported Languages, Versions, and Operating Systems.

To run your custom application, it is not necessary to have Automation1-MDK installed. But you must copy all the .NET API files to your target system. For a list of the files that are required based on your operating system, see Begin a New Project.

Thread Safety

The .NET API consists of thread-safe and non-thread-safe methods and properties. To learn about the thread safety of the controller features:

Read the documentation for each controller feature.
Refer to the Full References for Automation1 .NET API page. This page helps you find the documentation for the controller features. It also has an API diagram.

Use the .NET API in a Graphical User Interface

When you use the .NET API in a graphical user interface application, you must contend with these behaviors of the API:

Latency and Communication Loss - Most methods and properties in the .NET API communicate with the Automation1 controller. When they communicate, latency and communication loss can occur. You can install the Automation1 controller locally. Or you can install a remote Automation1 controller on a different device. If you install the controller remotely, the communication latency is higher and will be controlled by your local area network. This communication latency can add several milliseconds of delay to these methods and properties in the .NET API.

Methods That Block Until a Controller Operation Completes - Some methods in the .NET API will block until a controller operation completes.

For Example

Let's say that you execute a MoveLinear() AeroScript command through the Controller.Runtime.Commands.Motion.MoveLinear method. This method will block until the linear move is complete. One linear move can occur from 1 millisecond to multiple seconds.

WARNING: Because of these API behaviors, you must not call the .NET API methods and properties from the UI thread. If you do this, your UI will become unresponsive while the Automation1 controller does its operation.

For more information about the problems that can occur if you call .NET API methods and properties from the UI thread, refer to the use-case scenario that follows.

Use-Case Scenario - Call API Methods from the UI Thread

Let's say that you have a Windows Forms application with a Move button that moves your X axis 10 millimeters over 5 seconds with a speed of 2 millimeters per second. You decide to call API methods from the UI thread by doing the steps that follow:

You click the Move button. It executes a linear move through the Controller.Runtime.Commands.Motion.MoveLinear method in the button-clicked event handler.
There is also an Abort button that aborts all motion if an emergency occurs. You click this button. It executes an abort through the Controller.Runtime.Commands.Motion.Abort method in the button-clicked event handler.
You click the Move button again. Because the MoveLinear method was executed on the UI thread, your application freezes or becomes unresponsive for 5 seconds while the MoveLinear() AeroScript command is executing.

DANGER: During these 5 seconds, an emergency occurs!

You click the Abort button to abort all motion. But because the UI thread is blocked until the MoveLinear method is complete, that button cannot execute the Abort method.

As referred to in the example, it is very important for you to not block the UI thread. If you do, unsafe conditions can occur.

To Prevent Methods from Blocking the UI Thread

You must use threads or asynchronous programming. .NET gives you many different ways to use them. The decision is yours. The way in which you use threads or asynchronous programming does not have an effect on how the UI thread operates. This process is always the same. The UI thread does not call methods or properties in the .NET API. Instead, you must use a background thread that interacts with the .NET API. This interaction keeps the UI thread responsive.

You have some options that you can use to implement threads or asynchronous programming. They are as follows:

Use one background thread that interacts with the .NET API.
Spawn a new thread for each operation on the controller.

IMPORTANT: For these two options, you must read and understand the thread safety of the .NET API and the operations that you are trying to do.

To learn more about threading in .NET, read these articles from Microsoft:

In the previous use-case scenario, the user blocked the UI thread by trying to call API methods from the thread. As a result, the user could not abort motion when an emergency occurred. But the user could have prevented this problem by executing the commands on new threads or .NET tasks. By doing one of these options, a new use-case scenario can occur as follows.

Use-Case Scenario - Call API Methods by Spawning New Threads

You click the Move button. It executes a linear move through the Controller.Runtime.Commands.Motion.MoveLinear method in a new thread that is spawned in the button-clicked event handler.
There is also an Abort button that aborts all motion if an emergency occurs. You click this button. It executes an abort through the Controller.Runtime.Commands.Motion.Abort method in a new thread that is spawned in the button-clicked event handler.
You click the Move button again. Because the MoveLinear method is executing on a background thread, your application stays responsive for the 5 seconds that are necessary for the command to fully execute.

DANGER: During these 5 seconds, an emergency occurs!

You click the Abort button to abort all motion. Because each command is executing on a background thread and Commands is thread safe, the abort executes immediately. The abort stops all motion and the linear move stops.