.NET API

The AggreGate Server open-source Application Programming Interface for .NET (AggreGate Server .NET API) is a convenient library for accessing AggreGate Server from any .NET-based application using Web Service or AggreGate Communication Protocol.

An Application Programming Interface (API) is an interface that a program or library provides for other computer programs, to let them make requests to it.

Features of .NET API

Using this API, you can:

•	Access server resources and connected devices;

•	Modify server and device configuration;

•	Execute server and device operations;

•	Acquire server and device events;

•	Connect to AggreGate Server in "device mode", i.e. write .NET code that emulates or implements a hardware device connected to AggreGate.

Technically, the .NET API provides the following functionality:

•	Full access to the server contexts through a so-called proxy context tree;

•	Getting and setting values of context variables;

•	Calling context functions;

•	Listening for context events (only when using AggreGate Protocol);

•	Creating and manipulating Data Tables;

•	Emulating Agent.

.NET API Distribution Package

The AggreGate .NET API is available as a ZIP archive that contains:

•	Source code

•

Examples

•	Microsoft Visual Studio solution

Essential Classes and Interfaces of the .NET API

Class Name	Description
RemoteLinkServer	A container server connection parameters (address, port, username and password). An instance of this class is passed to the constructor of RemoteLinkServerController.
RemoteLinkServerController	This class is used to establish and control connection with the AggreGate Server. It provides access to a ContextManager interface which, in turns, lets you access the server's context tree.
ContextManager	Interface that provides access to the context tree. An instance of the class implementing this interface may be retrieved from the RemoteLinkServerController through the getContextManager() method.
Context	Interface letting you work with a single context. Instances of classes implementing this interface are returned by different methods of ContextManager.
DataTable	Implementation of a Data Table. It provides access to the format and records of the table. Instances of this class are returned by getVariable() and callFunction() methods of Context.
DataRecord	Implementation of a single Data Table record.
TableFormat	Class implementing format of a Data Table. It includes table properties and a list of fields.
FieldFormat	Class implementing format of a single Data Table field. Defines name, type and other parameters of the field, including validators, selection values etc.

Accessing AggreGate Server From .NET Application via Web Service

To access AggreGate Server from a .NET application using Web Service, create a LinkServerClient object in your application by calling its constructor with the Web Service address and AggreGate Server user name/password.

Following is the LinkServerClient constructor's signature:

public LinkServerClient(String username, String password, String url)

Example: creating a AggreGate Server client object in C#:

String webServiceAddress = "https://localhost:8443/ws/services/LinkServerWeb";

String userName = "admin";

String userPassword = "admin";

LinkServerClient lsc = new LinkServerClient(userName, userPassword, webServiceAddress);

To access the Web Service via HTTPS, it is necessary to set up a certificate policy first. For example (in C#):

System.Net.ServicePointManager.CertificatePolicy = new TrustAllCertificatePolicy();

public class TrustAllCertificatePolicy : System.Net.ICertificatePolicy

{

public TrustAllCertificatePolicy()

{ }

public bool CheckValidationResult(ServicePoint sp, X509Certificate cert, WebRequest req, int problem)

{

return true;

}

The LinkServerClient object implements all methods defined by the AggreGate Server Web Service:

•

getXML

•

setXML

•

callXML

•	setByStringArray

•	callByStringArray

•

get

•

set

•

call

getXML, setXML, callXML, setByStringArray and callByStringArray methods are comprehensively described in Web Service article. In most cases it is more convenient to use get, set and call methods that represent Data Tables as objects of type DataTable that is defined in AggreGate namespace. Here are signatures of all methods provided by LinkServerClient:

Methods that use XML encoding of Data Tables

public String getXML(String context, String variable)

public void setXML(String context, String variable, String value)

public String callXML(String context, String variable, String parameters)

Methods that represent Data Tables as string arrays

public void setByStringArray(String context, String variable, String[] values)

public DataTable callByStringArray(String context, String variable, String[] values)

Methods that process Data Tables as objects

public DataTable get(String context, String variable)

public void set(String context, String variable, DataTable value)

public DataTable call(String context, String variable, DataTable parameters)