About the .NET API

The .NET API for Automation1 lets you develop custom applications written in any .NET language to interact with an Automation1 controller. With the .NET API, you can connect to a controller to get status, execute commands, run your process, and more.

Throughout this documentation, the term .NET API refers to the Automation1 .NET API by Aerotech. The term .NET refers to the runtime environment created by Microsoft and the .NET Foundation.

The .NET API is packaged with Automation1-MDK. After you install Automation1-MDK, you can find the .NET API installed under C:\Program Files\Aerotech\Automation1-MDK\APIs\DotNet.

Some example programs are also installed with Automation1-MDK. They are installed under C:\Program Files\Aerotech\Automation1-MDK\Examples\DotNet and will demonstrate how to interact with an Automation1 controller through the .NET API. They show common features and use-cases in ways that are easy to understand. They also show you how to create Visual Studio projects for the .NET Framework version of the .NET API.

Supported Languages, Versions, and Operating Systems

The .NET API lets you use any .NET programming language, including but not limited to:

• C#
• F#
• VB.NET
• C++/CLI

The .NET versions that follow are supported:

• .NET Framework 4.6.2 or newer
• .NET Core 3.0 or newer
• .NET 5.0 or newer

The operating systems that follow are supported:

• Windows 10 32-bit or Windows 11 32-bit
• Windows 10 64-bit or Windows 11 64-bit
• Debian 10 64-bit x64

The .NET API first became available for Windows in Automation1 version 1.0 and Linux in Automation1 version 2.0. For more information about API versioning, see the Automation1 APIs page.

A 64-bit x64 Linux operating system with one of the configurations that follow might be compatible but is not supported:

• GLIBC 2.28 or newer
• GLIBCXX 3.4.25 or newer

Begin a New Project

After you install Automation1-MDK, you can find the .NET API installed under C:\Program Files\Aerotech\Automation1-MDK\APIs\DotNet. The net462 folder is for .NET Framework. The netstandard2.1 folder is for .NET Core, .NET 5, and .NET 6.

Some example programs are also installed with Automation1-MDK. They are installed under C:\Program Files\Aerotech\Automation1-MDK\Examples\DotNet and will demonstrate how to interact with an Automation1 controller through the .NET API. They show common features and use-cases in ways that are easy to understand. They also show you how to create Visual Studio projects for the .NET Framework version of the .NET API.

The .NET API contains several assembly and library files that are required to build and run a custom .NET application. They are as follows:

• Aerotech.Automation1.DotNet.dll
• Aerotech.Automation1.DotNet.xml
• Aerotech.Automation1.Communication.dll
• Automation1Compiler.dll
• Automation1Compiler64.dll
• libautomation1compiler.so

The exact files required for an application that you build will depend on your runtime operating system.

Aerotech.Automation1.DotNet.dll and Aerotech.Automation1.Communication.dll are .NET assemblies. You must add them to your project as .NET references.

Aerotech.Automation1.DotNet.xml is required for Visual Studio's IntelliSense feature. Without this file, the .NET API documentation will not be available to you while you do programming in Visual Studio.

Automation1Compiler.dll and Automation1Compiler64.dll are unmanaged libraries for Windows. You cannot add these libraries to your project as .NET references. But they are required at runtime if your program runs on Windows.

libautomation1compiler.so is an unmanaged shared object for Linux. You cannot add this shared object to your project as a .NET reference. But it is required at runtime if your program runs on Linux. You must install this file on your Linux operating system or add it to LD_LIBRARY_PATH.

Write Code Against the .NET API

Before you write code, you must access the .NET API by including the Aerotech.Automation1.DotNet namespace. All .NET API types are in this namespace. It is the only namespace that you must access to use the .NET API. After you get the namespace, you can begin to do work with an Automation1 controller.

The .NET API revolves around the Controller class. You can access all the controller features through an instance of the Controller class. Typically, it is not necessary for you to construct objects in the .NET API. Instead, you access features through properties on the Controller object. Refer to the example that follows.

To get information about what your controller is currently doing:

Controller.Runtime.Status.GetStatusItems(...)

To get an instance of a Controller object, you must connect to an Automation1 controller. There are static methods on the Controller class that will connect to an Automation1 controller and return a Controller object. Refer to the example that follows.

To connect to a locally installed PC-based controller:

Controller.Connect()

For more information about the Controller class, see the Controller page. Then read the pages for the features that you want to use:

• Status - Get information about what your controller is currently doing.
• Data Collection - Collect a snapshot of real-time, deterministic data over a period of time.
• Commands - Execute AeroScript commands on your controller.
• Tasks - Run and manage your AeroScript programs.

Principles of the .NET API

Framework

The .NET API uses Microsoft's Framework Design Guidelines.

Documentation

You can access in-code documentation for the .NET API through Visual Studio's IntelliSense.

Types (Classes and Enums)

All types, which are classes and enums, are in the Aerotech.Automation1.DotNet namespace. To get access to the .NET API, you must use, include, or import this namespace.

Connect to an Automation1 Controller

Each instance of the Controller class represents one connection to one controller.

Use the static Controller.Connect method to connect to an Automation1 controller.

You can connect to one or more Automation1 controllers at the same time in the same custom application. You can also connect to the same Automation1 controller multiple times at the same time.

When you connect an Automation1 controller, this process does not automatically start it. When you disconnect a controller, this process does not stop it.

Features

You can access all the .NET features through an instance of the Controller class. This class also has properties that you can use to access all the controller features.

For Example: To get information about what your controller is currently doing, use the Controller.Runtime.Status property.

The Controller.Runtime property represents features that you can access only if the controller is started and running.

Objects and Classes

Typically, it is not necessary for you to construct objects in the .NET API.

You can access controller features through properties on the Controller class. Use the static Connect methods to get an instance of this class.

The configuration objects StatusItemConfiguration and DataCollectionConfiguration are the only classes that you must construct.

Status and Information Updates

To get status and information updates, you must poll the controller. See the Status page for more information.

The only event-driven API is the Controller.Information property.

There are no events for errors and axis faults.

Axes

When you must specify an axis, you can use the axis name or the axis index.

Tasks

When you must specify a task, you can use the task name or the task index.

.NET Example Code

This code is written in C#.

1
2
3
4
5
6
7
8
9
10
11
12
// Connect to the iSMC installed on this PC. You can specify an IP address to connect to a remote controller.
Controller controller = Controller.Connect();
 
// Start the Automation1 controller that you are connected to. Do this to make sure the controller is running.
controller.Start();
 
// Because the controller is running, you can access the controller.Runtime property.
controller.Runtime.Commands.Motion.Enable("X");
 
// Disconnect from the controller when you are done interacting with it.
// When you disconnect the controller, this process does not stop the controller. The controller continues to run.
controller.Disconnect();

For more information and examples, see the Controller page.

More Reading

Now that you know what the .NET API for Automation1 is, read the pages that follow to learn more:

• .NET API Guidelines
• Full References for Automation1 .NET API