Scripts Module (How-to Guide)

Scripts → Tutorial | Concept | How-to Guide | Reference

Configuration Workflow

1. Create ScriptClasses - Build reusable function libraries
2. Create ScriptTasks - Implement automated processes
3. Add ScriptExpressions - Simple one-line actions
4. Add ScriptReferences - Include external DLL libraries
5. Test and Debug - Verify script execution

Step 1: Create ScriptClasses

ScriptClasses are libraries of reusable methods available throughout your solution.

Creating a Class

1. Navigate to Scripts → Classes
2. Click Plus icon
3. Configure:
   • Name: Class identifier
   • Code: Language (C#, VB.NET, Python)
   • Domain: Server or Client execution
   • ClassContent: Methods (standard) or Namespace (advanced)
4. Click OK
5. Double-click to open Code Editor

Built-in Classes

Example Class Code

<ac:structured-macro ac:name="warning"> ac:rich-text-body Important: ScriptClasses with Methods type contain only method definitions - NO class declaration wrapper </ac:rich-text-body> </ac:structured-macro>

csharp

// CORRECT - Methods directly, no class wrapper
public double CalculateEfficiency(double input, double output)
{
    if (input == 0) return 0;
    return (output / input) * 100;
}

public void LogEvent(string message)
{
    @Alarm.AuditTrail.AddCustomMessage(message);
}

public string GetStatus(double value, double limit)
{
    return value > limit ? "High" : "Normal";
}

Step 2: Create ScriptTasks

ScriptTasks execute code based on triggers or schedules.

Creating a Task

1. Go to Scripts → Tasks
2. Click Plus icon
3. Configure:
   • Name: Task identifier
   • Code: Language selection
   • Domain: Server (default) or Client
   • Trigger: Execution condition
   • Period: Time interval (if periodic)
   • InitialState: Enabled or Disabled
4. Click OK
5. Double-click to edit code

Built-in Tasks

Trigger Options

Example Task Code

<ac:structured-macro ac:name="warning"> ac:rich-text-body Important: ScriptTasks contain only the method body - NO function declarations or wrappers </ac:rich-text-body> </ac:structured-macro>

csharp

// CORRECT - Code directly, no method wrapper
// Task: MonitorProduction
// Trigger: @Tag.ProductionRun

if (@Tag.ProductionRun == 1)
{
    @Tag.StartTime = DateTime.Now;
    @Tag.BatchNumber = @Tag.BatchNumber + 1;
    
    // Call class method
    @Script.Class.ServerMain.LogEvent("Production Started");
}
else
{
    @Tag.EndTime = DateTime.Now;
    TimeSpan duration = @Tag.EndTime - @Tag.StartTime;
    @Tag.BatchDuration = duration.TotalMinutes;
}

Step 3: Add ScriptExpressions

Expressions are single-line VB.NET statements for simple operations.

Creating an Expression

1. Navigate to Scripts → Expressions
2. Add new row with:

Expression Methods

IIF Method (all parameters evaluated):

vbnet

Tag.Status = IIF(Tag.Value > 100, "High", "Normal")
' Both "High" and "Normal" are evaluated

TIF Method (conditional evaluation - recommended):

vbnet

Tag.Result = TIF(Tag.Mode = 1, Script.Class.ServerMain.Method1(), Script.Class.ServerMain.Method2())
' Only executes Method1() OR Method2(), not both

Common Expression Examples

vbnet

' Mathematical
Tag.Average = (Tag.Value1 + Tag.Value2) / 2

' Conditional
Tag.Alarm = Tag.Temperature > Tag.Setpoint

' Method call
Tag.Efficiency = Script.Class.ServerMain.CalculateEfficiency(Tag.Input, Tag.Output)

' String manipulation
Tag.FullName = Tag.FirstName + " " + Tag.LastName

' Using TIF for conditional execution
Tag.Status = TIF(Tag.Running, "Active", "Stopped")

Step 4: Add External References

Adding DLL References

1. 
   

   Go to Scripts → References

2. Click Plus icon
3. Browse and select DLL file
4. Configure:
   • Name: Reference identifier
   • Domain: Server or Client
5. Click OK

DLL Location Best Practices

Adding Namespaces

1. Open Code Editor
2. Click Namespace Declarations button
3. Add required namespaces in dialog:

csharp

System.Data
System.Linq
MyCustomLibrary

Step 5: Test and Debug

Enable Debugging

1. Go to Runtime → Build and Publish
2. Enable Debug Information
3. Save solution

Using the Debugger

1. Start runtime (F5)
2. Go to Runtime → Startup
3. Click Connect
4. Open script in Code Editor
5. Click Attach .NET Debugger
6. Set breakpoints by clicking line numbers
7. Use step controls when stopped

Monitoring Execution

Check script performance:

csharp

// Access in expressions or displays
@Script.Task.MyTask.ExecutionCount    // Number of executions
@Script.Task.MyTask.LastCPUTime       // Last execution time
@Script.Task.MyTask.State             // Running or Idle

Code Editor Features

IntelliSense

• Type @ to see all namespaces
• Type . after objects for properties
• Automatic method completion
• Parameter hints

Productivity Tools

Toolkit Methods

Common operations via TK namespace:

csharp

// Type conversion
double value = TK.ConvertTo<double>("123.45");

// Tag to DataTable
DataTable dt = TK.TagsToDataTable("Tag.*");

// Dynamic property access
object val = TK.GetObjectValue("Tag.MyTag");

Common Issues

Script Not Executing

• Check trigger configuration
• Verify InitialState is Enabled
• Review BuildStatus for errors
• Confirm domain (Server/Client) matches deployment

Compilation Errors

• Check BuildStatus column (red X indicates errors)
• Double-click to see error details
• Verify namespace declarations
• Ensure correct code structure (no wrappers)

DLL Not Found

• Use macros instead of absolute paths
• Place in correct folder (ThirdParty/WpfControls)
• Restart Designer after DLL updates
• Check Resolved status in References

Performance Issue

• Monitor LastCPUTime property
• Avoid infinite loops
• Use appropriate trigger type
• Consider execution frequency

Best Practices

Code Structure - Remember: no class/method wrappers in Tasks and Classes

Use descriptive names - Clear task and class identification

Handle exceptions - Platform provides automatic protection, but validate inputs

Reuse code- Create methods in ScriptClasses

Use @ symbol correctly - Required in Tasks/Classes, not in Expressions

Test incrementally - Verify BuildStatus after each change

Monitor performance - Check execution metrics regularly

Use TIF over IIF - Avoid unnecessary method execution in expressions

Script Examples

Data Calculation Task

csharp

// Task body only - no method wrapper
// Trigger: Period = 60000 (1 minute)

double production = @Tag.ProductionCount;
double runtime = @Tag.RuntimeHours;

if (runtime > 0)
{
    @Tag.ProductionRate = production / runtime;
    @Tag.Efficiency = @Script.Class.ServerMain.
        CalculateEfficiency(@Tag.PlannedProduction, production);
}

Alarm Response Expression

vbnet

' Object: Tag.AlarmMessage
' Expression:
TIF(Tag.Critical = 1, "CRITICAL: System Alert", "Normal Operation")

Client Display Initialization

csharp

// ClientStartup Task - body only
@Display.MainPage.UserLabel = @Client.UserName;
@Display.MainPage.LoginTime = DateTime.Now;
@Script.Class.ClientMain.LoadUserPreferences();

Next Steps

• [Display Code Behind →] Scripts in displays
• [Python Integration →] Configure Python scripts
• [API Integration →] External system connections

In this section...