EngWrapper API

The EngWrapper API facilitates the automation of engineering solutions, allowing developers to generate outputs directly from .NET programming environments. It supports data ingestion from CSV, XML, and JSON formats, streamlining the integration and processing of varied data sets within engineering applications. This API serves as a bridge between raw data inputs and customized engineering outputs.

On this page:

Requirements

This API requires the version 9.1.15 or newer. When installing the software, the Eng.Wrapper.dll will be installed inside of the binaries folder (xx-9.1). This is the file containing the EngWrapper API.

You must use a WebServer (TWebServer or IIS) configured to the software. When you create a new object for the Project class from the EngWrapper, it will use the WebServer to connect to the project. It is recommended to close the project before using the EngWrapper API or to open the project as a remote development. If you do not do this, you will see the new project configurations when you close and reopen the project.

Every method that adds configuration to a project adds an event to a queue. This event queue will be treated when the Commit method is called. The only methods that do not do this are the runtime methods and the methods that are related to the displays that start with the IntializeCreateDisplays and end with the FinalizeCreateDisplays methods.

There is a Microsoft Visual Studio solution with an example using this API available. Contact support for more information.

Using the EngWrapper API

The EngWrapper API allows C# or VB.NET applications to create and edit projects using third party applications.

When the software is installed, it will install the Eng.Wrapper.dll inside the binaries folder (xx-2016.2). This is the file containing the EngWrapper API.

For this feature, you will need to have a C# or VB.NET IDE installed on your computer. We recommend Visual Studio, as there is a sample solution already developed for it.

Through this IDE, you will be able to call one method to create items in the project, without the need to manipulate the project database.

You must use a WebServer (TWebServer or IIS) configured to the software. When creating a new object for the Project class from EngWrapper, it will use the WebServer to connect to the project. It is recommended to close the project before using the EngWrapper API or to open the project as remote development. If you do not do this, you will see the created project configuration when you close and reopen the project.

There are more details on every available method for the EngWrapper API on the documentation that comes with the sample project. Contact support if you do not have the project files.

To initiate the project configuration, you need to connect to a project using the syntax below:

public Project(
string projectFileName, string  version  =  "xx-8.1",
string server = "http://localhost/TProjectServer/", bool enableLogger = false,
bool assetLevel = true)
// Parameters:
// projectFileName: Full filename of the of project file
// version = Product version
//  server  =  TProjectServer  path.  Defaults:  http://IPAddress:Port/TProjectServer/
// enableLogger = Flag indicating whether log is enabled
// assetLevel = Indicates if the assetLevel is created

For more syntax on the other project objects (Tags, Templates, Devices, etc.), see the EngWrapper documentation.

Examples

This section contains examples on API usage in the C# programming language.

Connect to Project:

Project  project  =  new  Project(@"C:\Projects\Project.tproj","xx-8.1","http://localhost/TProjectServer/",true)

Add new Tag Name:

project.AddTag("Tag1","CommentTag1",Project.eTagType.Double,"V","25","0","800","","#1", tagDescription:"DescTag1");

project.AddTag("TagEnum1","CommentTagEnum1",Project.eTagType.Digital,tagParameters:"Enum=Enum1;", tagDescription:"DescTagEnum1");

Add Script Class:

string  script  =  "public  int  Add(int  a)"+ Environment.NewLine + "{" + Environment.NewLine +"\t"+
"return a + 1;" + Environment.NewLine +
"}" + Environment.NewLine;
project.AddScriptClass("class1",Project.eScriptCode.CSharp,Project.eDomain.Server,script);

Add Device Node:

project.AddDeviceNode("Node1","Channel1","192.168.10.19;502;1","192.168.10.19;503;1","Node  For  Channel1",0);

Add Device Point:

project.AddDevicePoint("Tag1","Label  for  Tag1","Node1",  "40001",Project.eDataType.Native,"", "ReadWrite",Project.PrepareScaling(0, 65535, 0, 800));

EngWrapper Syntax References

Connecting to Project

Syntax:

public Project(

string projectFileName,  

string version = "xx-9.1",

string server = "http://localhost/TProjectServer/",

bool enableLogger = false,

bool assetLevel = true)

Parameters:

projectFileName = Full file name of the project
version = Product version
server = The TProjectServer path. Default: http://IPAddress:Port/TProjectServer/
enableLogger = Flag indicating that a log is enabled
assetLevel = Indicates that the asset level is created

Return:

Project object (success)
Error message (fail)

Example:

Project project = new Project(@"C:\Projects\Project.tproj", "xx-9.1", "http://localhost/TProjectServer/", true)

Adding Device Channel

Syntax:

public object AddDeviceChannel( 
string channelName, 
string channelProtocol, 
string channelInterface, 
string channelDescription = "", 
string channelSettings = "", 
string channelTimeout = "", 
eInitialState channelInitialState = eInitialState.Enabled,
string channelProtocolOptions = “”)

Parameters:

channelName = Channel name
channelProtocol = Protocol
channelInterface = Interface type
channelDescription = Channel description
channelSettings = Channel settings
channelTimeout = Timeout
channelInitialState = Initial state
channelProtocolOptions=Protocol options

Return:

True (success)
Exception on failure

Example:

project.AddDeviceChannel("Channel1", "Modbus", "TCPIP", "Channel1", "Settings", Project.PrepareChannelTimeout(1000, 2000, 3000, 250, 5), Project.eInitialState.Enabled,
"BlockSize=250;Encoding=RTU TCP;SingleWrite=Use single write;SlaveID=2;CoilWriteValue=FF;Offset address=false");

Adding Device Node

Syntax:

  public object AddDeviceNode(
string nodeName, 
string nodeChannelName, 
string nodePrimaryConnection, 
string nodeSecondaryConnection = "", 
string nodeDescription = "", 
Int64 nodeCategory = 0, 
Int32 nodeLevel = 0, 
string syncSettings = "", 
string syncStation = "", 
string syncDate = "")

Parameters:

nodeName = Node name
nodeChannelName = Channel name
nodePrimaryConnection = Primary station
nodeSecondaryConnection = Secondary station
nodeDescription = Node description
nodeCategory = Category
nodeLevel = Assets level
syncSettings = Sync settings
syncStation = Sync station
syncDate = Sync date

Return:

True (success)
Exception on failure

Example:

project.AddDeviceNode("Node1", "Channel1", "192.168.10.19;502;1", "192.168.10.19;503;1", "Node For Channel1", 0);

Adding New User Template

Syntax:

public object AddUserTemplate(
string templateName)

Parameters:

templateName = Template name

Return:

True (success)
Exception on failure

Example:

project.AddUserTemplate("PID");

Adding New Member Name in User Template

Syntax:

public object AddMemberName(
string templateName, 
string memberName, 
string memberComment = "", 
object memberType = null, 
string memberUnits = "", 
string memberStartValue = "", 
string memberMin = "", 
string memberMax = "", 
string memberArray = "", 
string memberFormat = "", 
string memberParameters = "", 
eRetentive memberRetentive = eRetentive.None, 
eDomain memberDomain = eDomain.Server, 
eVisibility memberVisibility = eVisibility.Protected, 
string memberDescription = null)

Parameters:

templateName = Template name
memberName = Member name
memberComment = Comment
memberType = Type
memberUnits = Units
memberStartValue = Start value
memberMin = Min value
memberMax = Max value
memberArray = Array size
memberFormat = Format
memberParameters = Parameters
memberRetentive = Retentive
memberDomain = Domain
memberVisibility = Visibility
memberDescription = Description

Return:

True (success)
Exception on failure

Example:

project.AddMemberName("PID", "sp", memberType: Project.eTagType.Double, memberDescription: "Desc SP");

Adding New Tag Name

Syntax:

public object AddTag(
string tagName, 
string tagComment = "", 
object tagType = null, 
string tagUnits = "", 
string tagStartValue = "", 
string tagMin = "", 
string tagMax = "", 
string tagArray = "", 
string tagFormat = "", 
string tagParameters = "", 
int tagLevel = 1, 
eRetentive tagRetentive = eRetentive.None, 
eDomain tagDomain = eDomain.Server, 
eVisibility tagVisibility = eVisibility.Protected, 
string tagDescription = null)

Parameters:

tagName = Tag name
tagComment = Comment
tagType = Type
tagUnits = Units
tagStartValue = Start Value
tagMin = Min value
tagMax = Max value
tagArray = Array size
tagFormat = Format
tagParameters = Parameters
tagLevel = Assets level
tagRetentive = Retentive
tagDomain = Domain
tagVisibility = Visibility
tagDescription = Description

Return:

True (success)
Exception on failure

Example:

project.AddTag("Tag1", "Comments of Tag1", Project.eTagType.Double, "V", "25", "0", "800", "", "#1", tagDescription: "Desc Tag1");

project.AddTag("TagTemplate1", tagType: "PID", tagDescription: "Desc PID");
                
project.AddTag("TagEnum1", "Comments of TagEnum1", Project.eTagType.Digital, tagParameters:"Enum=Enum1;", tagDescription: "Desc TagEnum1");

Adding Device Point

Syntax:

public object AddDevicePoint(
string pointName, 
string pointLabel = "", 
string pointNode = "", 
string pointAddress = "", 
eDataType pointDataType = eDataType.Native, 
string pointModifiers = "", 
string accessTypeName = "ReadWrite", 
string pointScaling = "")

Parameters:

pointName = Tag name
pointLabel = Assets level
pointNode = Node name
pointAddress = Address
pointDataType = Data type
pointModifiers = Modifiers
accessTypeName = Access type name
pointScaling = Scaling

Return:

True (success)
Exception on failure

Example:

project.AddDevicePoint("Tag1", "Label for Tag1", "Node1", "40001", Project.eDataType.Native, "", "ReadWrite", Project.PrepareScaling(0, 65535, 0, 800));

Adding Alarm Area

Syntax:

public object AddAlarmArea(
string alarmArea, 
string alarmAreaParent = "")

Parameters:

alarmArea = Area name
alarmAreaParent = Parent area name

Return:

True (success)
Exception on failure

Example:

project.AddAlarmArea("Level1");
project.AddAlarmArea("Level2", "Level1");

Adding Alarm Group

Syntax:

string alarmGroupName, 
eAlarmAck alarmGroupAck = eAlarmAck.Ack, 
eAlarmSound alarmGroupSound = eAlarmSound.None, 
int alarmShow = 1, 
eAlarmLog alarmLog = eAlarmLog.ActiveNormAck, 
string ackTimeout = "", 
string autoAckTimeout = "", 
string alarmGroupActiveTextColor = "", 
string alarmGroupActiveBackgroundColor = "", 
string alarmGroupAckedTextColor = "", 
string alarmGroupAckedBackgroundColor = "", 
string alarmGroupNormalTextColor = "", 
string alarmGroupNormalBackgroundColor = "", 
int activeTimeDeadband = 0)

Parameters:

alarmGroupName = Group name
alarmGroupAck = Ack required
alarmGroupSound = Sound
alarmShow = Enable show
alarmLog = Log type
ackTimeout = Ack timeout
autoAckTimeout = Auto ack timeout
alarmGroupActiveTextColor = Active text color
alarmGroupActiveBackgroundColor = Active background color
alarmGroupAckedTextColor = Ack text color
alarmGroupAckedBackgroundColor = Ack background color
alarmGroupNormalTextColor = Normal text color
alarmGroupNormalBackgroundColor = Normal background color
activeTimeDeadband = Active time deadband

Return:

True (success)
Exception on failure

Example:

project.AddAlarmGroup("LogOnly", Project.eAlarmAck.Ack, Project.eAlarmSound.None, 0, Project.eAlarmLog.ActiveNormAck, "10000", "20000");

Adding Alarm Item

Syntax:

public object AddAlarmItem(
string alarmName, 
string alarmGroupName = "", 
string alarmMessage = "", 
Int32 alarmPriority = 0, 
string alarmArea = "", 
eCondition alarmCondition = eCondition.GreatherEqual, 
string alarmValue = "1", 
string alarmAuxValue = "", 
string alarmSetPoint = "", 
string alarmSetPointDeadband = "", 
string alarmComment = "")

Parameters:

alarmName = Tag name
alarmGroupName = Alarm Group name
alarmMessage = Message
alarmPriority = Priority
alarmArea = Area name
alarmCondition = Condition
alarmValue = Value
alarmAuxValue = Aux Value
alarmSetPoint = Set point
alarmSetPointDeadband = Setpoint deadband
alarmComment = Alarm comment

Return:

True (success)
Exception on failure

Example:

project.AddAlarmItem("Tag1", "LogOnly", "Tag1 Failure", 100, "Level2", Project.eCondition.Hi, "650");

Adding Historical Table

Syntax:

public object AddHistoricalTable(
string tableName, 
int autoCreate = 1, 
int saveOnChange = 1, 
int timeDeadBand = 0, 
int lifeTime = 0, 
string trigger = "", 
int saveQuality = 0 )

Parameters:

tableName = Table name
autoCreate = Auto create table
saveOnChange = Save on Tag Change
timeDeadBand = Time DeadBand
lifeTime = File lifetime
trigger = Save trigger
saveQuality = Save quality

Return:

True (success)
Exception on failure

Example:

project.AddHistoricalTable("Log1", 1, 1, 1000, 10, "Tag1");

Adding Historical Item

Syntax:

public object AddHistoricalItem(
string pointName, 
string pointHistoricalTable = "", 
double deadBand = 0, 
double deviation = 0, 
double rateOfChange = 0)

Parameters:

pointName = Tag name
pointHistoricalTable = Table Name
deadBand = Deadband
deviation = Deviation

Return:

True (success)
Exception on failure

Example:

project.AddHistoricalItem("Tag1", "Log1", 10);

Adding Expression

Syntax:

public object AddExpression(
string tagName, 
string expression, 
eExecution execution = eExecution.Trigger_OnChange, 
string disableCondition = "")

Parameters:

tagName = Tag name
expression = Expression
execution = Execution type
disableCondition = Disable condition

Return:

True (success)
Exception on failure

Example:

project.AddExpression("Tag1", "Tag.Tag1=0", Project.eExecution.Trigger_OnChange);

Adding Script Class

Syntax:

public object AddScriptClass(
string name, 
eScriptCode codeType, 
eDomain domain, 
string code)

Parameters:

name = Script class name
codeType = Code type
domain = Domain
Code = Code

Return:

True (success)
Exception on failure

Example:

string script = "public int Add(int a)" + Environment.NewLine +
                    "{" + Environment.NewLine +
                    "\t" + "return a + 1;" + Environment.NewLine +
                    "}" + Environment.NewLine;

project.AddScriptClass("class1", Project.eScriptCode.CSharp, Project.eDomain.Server, script);

Adding Script Task

Syntax:

public object AddScriptTask(
string name, 
eScriptCode codeType, 
string trigger, 
TimeSpan period, 
eDomain domain, 
string code)

Parameters:

name = Script task name
codeType = Code type
trigger = Trigger
period = Period
domain = Domain
Code = Code

Return:

True (success)
Exception on failure

Example:

script = "@tag2[1] = @Script.Class.Class1.Add(TK.To<int>(@tag2[1]));" + Environment.NewLine + "@tag2[2] = @tag2[2] + 2;" + Environment.NewLine;

project.AddScriptTask("task1", Project.eScriptCode.CSharp, "Server.Second", TimeSpan.Zero, Project.eDomain.Server, script);

Adding Enumeration Sets

Syntax:

public object AddEnumerationSets(
string name, 
string tagValue, 
string displayValue, 
string description = "")

Parameters:

name = Enumeration Sets name
tagValue = Value of tag
displayValue = Text display value
description = Description

Return:

True (success)
Exception on failure

Example:

project.AddEnumerationSets("Enum1", "0", "Open", "Description-Value0");
project.AddEnumerationSets("Enum1", "1", "Close", "Description-Value1");

Queue Item Commit to Database Project

Syntax:

public object Commit()

Return:

True (success)
Exception on failure

Example:

project.Commit();

Initializing Container of Displays

Syntax:

public void IntializeCreateDisplays(
System.Windows.Controls.Frame frame)

Parameters:

frame = WPF Control frame

Return:

None

Example:

project.IntializeCreateDisplays(this.frame);

Inserting Display

Syntax:

public void InsertDisplay(
string displayName, 
string listCSV)

Parameters:

displayName = Display name
listCSV = String format CSV

Return:

None

Example:

StringBuilder sb = new StringBuilder();
sb.AppendLine("Symbol,TagName,Top,Left,Labels,Uid");
sb.AppendLine("VerticalTank_Scale,,52,63,LevelValue=Tag3,VerticalTankScale3");
b.AppendLine("CurrentDisplay,,0,0,
Background=#FFFF0000;
Width=600;
Height=600;" +
                    "Mode=" + Project.eDisplayMode.Popup + ";" +
                    "CloseButton=1;" +
                    "Title=New Title;" +
                    "TitleBackground=#FFFF0000;" +
                    "Border=" + Project.eDisplayBorder.Thin +";" +
                    "Placement=" + Project.eDisplayPlacement.BottomLeft + ";" +
                    "Target=" + Project.eDisplayTarget.Mouse + ";" +
                    "DialogButtons=" + Project.eDialogButtons.YesNoCancel + ";" +
                    "Animation=" + Project.eOpenAnimation.Scroll
                    );

project.InsertDisplay("Page1", sb.ToString());

The available display properties are: Background, Width, Height, Mode, CloseButton, Title, TitleBackground, Border, Placement, Target, DialogButtons, and Animation.

Removing All Display Symbols

Syntax:

public void RemoveAllSymbols(
string displayName)

Parameters:

displayName = Display name

Return:

None

Example:

project.RemoveAllSymbols("MainPage");

Geting Symbols from a Display

Syntax:

public string GetDisplaySymbols(
string displayName, 
char sep = ',')

Parameters:

displayName = Display name
sep = Separator

Return:

String format CSV

Example:

string str = project.GetDisplaySymbols("MainPage");

Getting Display List

Syntax:

public string[] GetDisplays()

Return:

None

Example:

String[] displays = project.GetDisplays();

Finalizing Display Container

Syntax:

public void FinalizeCreateDisplays(
System.Windows.Controls.Frame frame)

Parameters:

frame = WPF Control frame

Return:

None

Example:

project.FinalizeCreateDisplays(this.frame);

Runtime Startup Command

Syntax:

public void RunStartup(
string userName, 
string password, 
bool connect, 
int timeoutSecWaitStarting = 60);

Parameters:

username = User name
password = User password
connect = Flag to connect to runtime after starting
timeoutSecWaitStarting = Timeout waiting runtime starts

Return:

None

Example:

project.RunStartup("Guest", "", true, 60);

Runtime Shutdown When RunStartup Method Starts

Syntax:

public void ShutdownRuntime();

Return:

None

Example:

project.ShutdownRuntime();

Checking if Runtime is Running

Syntax:

 public bool IsRuntimeRunning();

Return:

Is running (true)
Is not running (false)

Example:

bool isRunning = project.IsRuntimeRunning();

Applying Changes to Current Runtime (Hot Start)

Syntax:

public void HotStartup(string userName, string password);

Parameters:

username = User name
password = User password

Return:

None

Example:

project.HotStartup("Guest", "");

Connecting to Runtime to Enable Online Configuration

Syntax:

public void ConnectToRuntime(int timeoutSecWaitStarting = 60);

Parameters:

timeoutSecWaitStarting = Timeout waiting connection to runtime

Return:

None

Example:

project.ConnectToRuntime(60);

Disconnect from Runtime to Disable Online Configuration

Syntax:

public void DisconnectFromRuntime();

Return:

None

Example:

project.DisconnectFromRuntime();

Checking Connection with Runtime

Syntax:

public bool IsConnectedToRuntime();

Return:

Is connected (true)
Is not connected (false)

Example:

bool isConnected = project.IsConnectedToRuntime();

In this section:

Space shortcuts

Page tree

EngWrapper API

Requirements

Using the EngWrapper API

Examples

EngWrapper Syntax References

Connecting to Project

Syntax:

Parameters:

Return:

Example:

Adding Device Channel

Syntax:

Parameters:

Return:

Example:

Adding Device Node

Syntax:

Parameters:

Return:

Example:

Adding New User Template

Syntax:

Parameters:

Return:

Example:

Adding New Member Name in User Template

Syntax:

Parameters:

Return:

Example:

Adding New Tag Name

Syntax:

Parameters:

Return:

Example:

Adding Device Point

Syntax:

Parameters:

Return:

Example:

Adding Alarm Area

Syntax:

Parameters:

Return:

Example:

Adding Alarm Group

Syntax:

Parameters:

Return:

Example:

Adding Alarm Item

Syntax:

Parameters:

Return:

Example:

Adding Historical Table

Syntax:

Parameters:

Return:

Example:

Adding Historical Item

Syntax:

Parameters:

Return:

Example:

Adding Expression

Syntax:

Parameters:

Return:

Example:

Adding Script Class

Syntax:

Parameters:

Return:

Example:

Adding Script Task

Syntax:

Parameters: