Introduction to EngWrapper API

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. 

On this page:


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: