.NET API

 Top  Previous  Next

The LinkServer .NET Application Programming Interface (API) provides convenient classes for accessing the  LinkServer Web Service from any .NET-based application. Using this API, you can get and set values of context variables and call context functions, and thus fully control the server and all hardware devices in the AggreGate installation. The API also provides classes for creating and processing Data Tables.

.NET Library Distribution Package

The AggreGate .NET library is available as a ZIP archive that contains two Dynamically Linked Libraries (DLL):

•LinkServerClient.dll for accessing LinkServer through a Web Service.
•AggreGate.dll for managing Data Tables in C# and other CLR-compatible languages.

These libraries are located in the /dll folder of the archive.

The archive also contains the source code for these libraries, several examples and a Microsoft Visual Studio solution for building them.

Accessing LinkServer From .NET Application

To make use of AggreGate .NET library you need to add both LinkServerClient.dll and AggreGate.dll in your project and create references to them. After that you can create a LinkServerClient object in your application by providing its constructor with the Web Service address and LinkServer user name/password:

 

Following is the LinkServerClient constructor's signature:

 

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

 

note_example-wt

Example: creating a LinkServer client object:

 

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

String userName = "admin";

String userPassword = "admin";

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

note_further-wt

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

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 LinkServer 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)

 

The AggreGate namespace defines several classes for managing Data Tables. Here is a list of most important classes:

Class Name

Description

DataTable

An instance of this class represents a Data Table. It provides access to the format and records of the table.

DataRecord

A single record of the data table. This class lets you access record data.

RecordFormat

This class describes the format of the Data Table. It includes table properties and a list of fields.

FieldFormat

A descriptor for a single Data Table field. Defines name, type and other parameters of the field, including validators, selection values etc.

Example

This example shows how to connect to the LinkServer from a C# application and browse Device Servers of a particular user. The complete code for this example is available in the .NET library distribution package.

 

// Defining certificate policy to allow access to LinkServer Web Service

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

 

String linkServerHost = "localhost";

String userName = "admin";

String userPassword = "admin";

 

Console.Out.WriteLine("Exploring Device Servers of user: " + userName);

 

String webService = "https://" + linkServerHost + ":8443/ws/services/LinkServerWeb";

 

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

 

// Constructing path of Device Servers context

String deviceServersContext = "users." + userName + ".deviceservers";

 

// Getting "status" variable that contains status of all Device Servers

AggreGate.DataTable res = lsc.get(deviceServersContext, "status");

 

// Iterating over all records

for (int i = 0; i < res.getNumberOfRecords(); i++)

{

       // Getting Device Server name

       String dsName = res.getRecord(i).getString("name");

 

       // Getting Device Server online status

       java.lang.Boolean online = res.getRecord(i).getBoolean("online");

 

       Console.Out.WriteLine("Device Server #" + i + ": '" + userName + "." + dsName + "', " + (online.booleanValue() ? "online" : "offline"));

}