| HTML |
|---|
<style>
.text-span-6 {
background-image: linear-gradient(99deg, rgba(170, 163, 239, .5), rgba(125, 203, 207, .5));
border-radius: 50px;
padding-left: 15px;
padding-right: 15px;
}
#title-text {
display: none;
}
.panelgradient {
background-image: linear-gradient(180deg, #d5def0, whitesmoke);
border-radius: 8px;
flex-direction: column;
justify-content: center;
align-items: center;
padding: 4rem;
display: flex;
position: relative;
}
</style>
<div class ="panelgradient">
<h1 style="text-align: center;">Scripts <br> (Tasks and Classes)</h1>
</div> |
Introduction to the Scripts Module
The Scripts Module supports multiple programming languages, including
Introduction to the Script module
The Script module is a powerful feature that allows users to execute custom code and enhance the system's functionality, particularly in the context of industrial automation. Supporting various programming languages, such as C#, VB.NET, Python, and JavaScript, it enables enabling the creation of high-performance server-side and client-side scripts that seamlessly integrate into projects, catering to tailored solutions for specific needs.This powerful tool offers a comprehensive set of features, including multi-threaded task execution, event-driven actions, creation of libraries for methods and classes, and integration with third-party libraries. The in Display Code-Behind. Its built-in code editor streamlines development with automated translation between C# and VB.NET and provides access to all .NET Framework classes available in Visual Studio. Furthermore, the Script The module simplifies the development of distributed applications by distributed application development using server or client domains and ensuring ensures high performance through the compilation of custom code .The Script module also allows users to extend graphics displays power by implementing Display Code compilation. Additionally, it enhances graphical displays with Display Code-Behind functions and provides offers debugging tools for quick identification and resolution of coding issues. With seamless integration of Python language and applications, the Script module delivers exceptional scripting capabilities across various programming languages, enabling users to design and deploy powerful, custom solutions within a dynamic software environment.
The Scripts Module allows:
- Multi-Threaded Task Execution
- Event-Driven Actions
- Library Creation for Methods and Classes
- Intermixing C#, VB.NET and Python classes.
- Integration with Third-Party Libraries.
On this page:
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
Key Concepts and Terms
The Scripts module Module manages and executes user-defined scripts for automation and process control. It involves key concepts such as Script Tasks, Classes, Expressions, and References, which help create, manage, and interact with script-related objects.
Script Tasks
ScriptTask
Defines A Script Task defines a code that executes in reaction to an event (trigger) or periodically at specified intervals. For example, you can create a Task to execute every second, or when any specific Tag in the Project has a new Value.
Script Classes
.
ScriptClass
A A Script Class is a library of functions and methods that you can consume on be used in Script Tasks, Expressions, or from the Code Behind on the graphical Displays. The use of Scripts Classes allows a more efficient and clean organization of Project logic and calculations.
Script Expressions
ScriptExpression
One When you need to execute one line of code in a reaction response to an event, instead of creating a Script Task, you can configure just one line at the Script Expressions table. For example, when one tag changes its value, you need to set another tag value, or call a Script Class, it is easier to define just the one line Expression instead of a Taskthe entire script isn't necessary.
Script References
Script References are external External DLLs included for a script or display code compilation.
Understanding the
Script moduleFeatures highlights
Scripts Module
Module Highlights
Multi-threading execution of many tasks and event driven actions.
Create libraries of methods and classes.
Adding references and using externally created libraries.
Built-in Code Editor with automated translation between C# and VB.NET
All the .NET Frameworks classes available at Visual Studio are also available in our editor.
Use the concept of Server or Client domains to facilitate development of Distributed Applications
High performance as all the use custom code created is compiled, not interpreted.
Extend the Graphics Displays power by providing Display Code Behind functions.
Easy Integration with Python language and applications.
Scheduling Tasks using Triggers
Content
Function Libraries in Script Classes
Content
Event-Driven Expressions
Content
Using Scripts on Displays
Content
Configuring the Script module
Configuration Workflow
Manage Class Scripts
Scripts→ Classes
Manage Task Scripts
Scripts→ Task
Manage Expressions
Scripts→ Expressions
Manage References
Scripts→ References
Track the module changes
Scripts→ Monitor
Script Tasks Configuration
Tasks are program units, written in VB.Net or C#, that execute either when a trigger event occurs or periodocally at specified intervals.
Project Built-in Tasks
All Projects includes the following built-in tasks:
- ServerStartup: executed when the project starts running. Runs on the server (computer running TServer.exe).
- ServerShutdown: executed when the project shuts down. Runs on the server.
- ClientStartup: executed on each client when the Displays module starts running.
- ClientShutdown: executed on each client when the Displays module close.
Creating and Editing Tasks
To configure tasks:
Go to Edit → Scripts → Tasks.
Select a task name, or select the insertion row (first blank row) to create a new task.
Enter or edit fields as needed.
Configuring a task involves setting several properties that determine how and when the task will run. Here are some common task properties:
Script Task Configuration Properties
Column / Field
Description
Name
Enter a name for the task. The system allows you to know if the name is not valid.
Code
Read-only. This specifies the language used for the code for this task. By default, this is the language you selected when you created the project. From the CodeEditor, you can change the code language. To change the project default, go to Info → Settings.
Trigger
Enter or select the event (tag or other object) that should trigger the task execution, if any. The task executes when the value of the object changes.
Period
Enter the time interval that should occur between executions of the task, if there is no trigger.
Domain
Select where the script executes:
Client: task executes on each client system. These are tasks that apply locally (on the user's computer). For example, report generation.
Server: task executes on the server system. These are tasks that apply across the application, that is, globally.
InitialState
Select the task's initial state:
Enabled: task is ready to run.
Disabled: task is not ready to run. You may enable the task under specific conditions.
BuildStatus
Read-only. Status of the task code from the continuous compiling process.
Green check mark: task runs without errors.
Red X: task has warnings or errors. Double-click to go to the warning or error. Warnings are information only. Errors will prevent the code from running for that specific task. The rest of the application will run.
BuildErrors
Read-only. Displays any errors encountered during the last build.
EditSecurity
Set the security to enable who can edit the tasks.
Description
Enter a description of this task.
Script Classes Configuration
Classes allows you to create a repository of class libraries, methods, and functions that you can use across the application. You can call them from tasks, other classes, and displays (code behind).All Projects come with the following built-in classes:
ServerMain: the purpose of this class is to provide functionalities for server-side task management. This methods library runs on the server computer, i.e., the computer running the TServer.exe file.
ClientMain: the purpose of this class is to provide functionalities for client-side task management. This method library is targeted toward clients using the .NET platform.
Creating and Editing Script Classes
To configure Script Classes:
Go to Edit → Scripts → Classes.
Select a class name, or select the insertion row (first blank row) to create a new class.
Enter or edit fields as needed.
Class configuration typically involves setting properties that determine the class behavior. Here are some common Script Class properties:
Script Class Configuration Properties
Field
Description
Name
Enter a name for the class. The system lets you know if the name is not valid.
Code
Read-only. This specifies the language used for the code for this task. By default, this is the language you selected when you created the project. From the Code Editor tab, you can change the code language. To change the project default, go to Project → Settings.
Domain
Select where the class executes:
Client: class executes on each client system. These are classes that apply locally (on the user's computer). For example, report generation.
Server: class executes on the server system. These are classes that apply across the application, that is, globally.|
Content
Read-only. Shows the type of the content in the class (e.g.: method or namespace)
EditSecurity
Set the security to enable who can edit the tasks
BuildOrder
Set the order to build the classes
BuildStatus
Read-only. Status of the class code from the continuous compiling process.
Green check mark: Class runs without errors.
Red X: Class has warnings or errors. Double-click to go to the warning or error. Warnings are information only. Errors will prevent the code from running for that specific class. The rest of the application will run.
BuildErrors
Read-only. Displays any errors encountered during the last build.
Description
Enter a description of this class.
Script Expressions Configuration
Besides the Script → Expressions table, you can use expressions in several other places by using the syntax described here. This can be done to determine a value or to configure a condition.
Expressions are plain VB.Net expressions, such as arithmetic expressions or calls to script.class methods from the project. IntelliSense only shows tags and application objects, but the expressions are compiled using the standard VB.Net compiler. Whatever you would write in the code editor should be accepted in expressions as well.
Our platform implements automated replacements, such as"==" to "=". The syntax of an expression is close to a C# statement but without a need to add the semicolon “;” at the end.Therefore, both VB.Net and C# programmers are able to use the expression fields seamlessly.
In expressions, you do not need to put an "@"before tag names. You need the "@" in the code editor to differentiate project tags from .NET variables. However, expressions do not have local .NET variables, so you use the project object directly.For arithmetic operands, use the standard operands as described in the .NET documentation.
To allow single-line evaluations, the .NET language has the IIF command, which currently is used only with VB.Net. The IIF command has three parameters.
Example: IIF (A, B, C)
The first parameter is a condition. This method will return B if condition A is true, and it returns C if the condition is false.
IIF (tag.A = 1, "True", "False") will return the string "True" if the value of tag.A is 1, or "False" if tag.A has a different value.
IIF (tag.A = 1, script.class.client.Func1(), script.class.client.Func2()), both Func1and Func2will always be executed. Only the return value will be different based on the value oftag.A.The IF or IIF methods need to evaluate the parameters before calling the method. There are many scenarios where you may want to execute only the function according to the value. For these scenarios, FactoryStudio has a method called TIF.
Use the expression:
TIF (tag.A = 1, script.class.client.Func1(), script.class.client.Func2())
Func1()or Func2() will be executed, according the value of Tag.AThe TIF method is defined in the class library that is automatically exposed to expressions that are in the toolkit function library.
For more complex calculations, you can call a class that you create on the Classes tab. See Configuring Classes earlier in this chapter.
Adding or editing Script Expression
Go to Scripts → Expressions.
Select an expression, or select the insert row (first blank row) to create a new expression.
Enter or select information, as needed.
Script Expressions Configuration Properties
Field
Description
Object
Select an existing tag or object.
Expression
Enter the expression. The expression can be a basic mathematical expression, a class, or a conditional expression.
Domain
Select where the expression executes:
- Client: expression executes on each client system. These are expressions that apply locally (on the user's computer). For example, report generation.
Server: expression executes on the server system. These are expressions that apply across the application, that is, globally.|
Execution
Select when the expression executes:
OnChange: the expression executes when the value of any tag in the expression changes.
TriggerOrTimeInterval: the expression executes when the trigger event occurs or when the interval set in the period elapses.
ChangeOrStartup: the expression executes when the value of any tag in the expression changes or at startup.
TriggerOrTimeOfDay: The expression executes when a trigger event occurs or on a specific time of day
Trigger
Enter or select the tag or object that triggers the expression execution. The expression executes when the value of the object changes.
DisableCondition
Enter or select the tag or object that disables the expression execution.
Time
Specify the time when the expression runs.
Label
Set a label to the specified class.
Build Messages
Return the message status after the expression runs
BuildStatus
Read-only. Set after you click Verify.
Green check mark: expression runs without errors.
Red X: expression has errors.
BuildErrors
Read-only. Displays any errors encountered during the last build.
Managing External References
If you need references to your own assemblies, you can use Project → Build → References.
As a fully compliant .NET application, you can find free source code to use, including .NET components, products, and libraries. Plus, you can use your own libraries.
Code Editor Overview
You can write code in either standard VB.Net or C#. You can also switch between both. If you change your language selection in the code editor, the system automatically converts existing code to the selected language.
For Python code, the editing is executed at the Python editor and a reference the program created is added.
To edit code:
Go to Edit → Scripts → CodeEditor.
From the drop-down list in the main toolbar, select the task or class you want to edit. To create a new task or class, see Scripts Tasks Configurations or Scripts Classes Configurations earlier on this page.
If needed, select a different code language from the code editor toolbar.
You can also format your code to be more readable. To do so, click Auto Format. A prompt will appear; click OK.
Click Save.
When Selecting Edit → Scripts → CodeEditor, the Code Editor environment is displayed with the contents of the last selected Script Task or Script Class.
While in that environment, you can change the task or class you are editing using the ComboBox at the top area.
Scripts Compilation
The Scripts Compilation utilizes an incremental compilation approach, which means that scripts are automatically compiled in the background as they are created or modified without requiring explicit user intervention. This approach ensures that only the necessary scripts are compiled, resulting in improved performance and reduced compilation time.
When a script is created or modified, the incremental compilation mechanism identifies the affected scripts and compiles them individually rather than recompiling the entire project. This targeted compilation minimizes the overhead associated with compiling unchanged scripts, resulting in faster build times.
Before deploying a project into a production environment, it is highly recommended to execute a build operation. This build operation ensures that all scripts are up-to-date and compiled correctly, reducing the chances of runtime errors or unexpected behavior.
| Info |
|---|
When you use the code editor, the system constantly compiles code in the background. You can also build the whole project, as needed. For more information, see Running the Application. |
Productivity Enhancements
IntelliSense: it is a code-completion aid that features listing the available properties and methods for the objects and auto completing their names. Additionally to the Properties and Methods of the .NET Framework, it also supports all Project entities, like Tags and Displays. Just type a dot "." after an element to show its available properties.
The Toolkit namespace: our platform exposes many .NET libraries to the application, but there are a few methods that are frequently required, such as type conversion, copying tags to DataTables and .NET objects, or dynamically changing the communication settings, and others. Those methods included in a library toolkit. To use these methods, you need to put
TK.in the code editor. IntelliSense will respond with a list of all available methods and provide a summary documentation for any method you select. Example:double x = TK.ConvertTo<double>("123");
Debugging and Error Handling
Creating debugger Information
The platform has an integrated .NET code debugger. In order to use it, the local computer must have a cache with the necessary files to run the debugger. The steps to enable the debugger are:
Enable the Debug Information on Run → Build → Messages.
As necessary, save the source code you want to debug. This will create the debug information. This step is only necessary the first time you open the project on the computer. Afterwards, the background compiling generates the necessary debugging information to enable the use of breakpoints and step execution.
Attaching the .NET debugger
In order to have a .NET debugging session, the engineering environment must be connected to the runtime, and the .NET debugger must be attached to server or client process. Follow these steps.
When Running the project, go to Run → Test or Run → Startup and enable the connect check box.
If the project is already running, go to Run → Test or Run → Startup, according to the runtime you want to attach, and connect to the runtime system by pressing the connect button on those pages.
Open any script that has debugging information and press the Attach .NET debugger button. A message on the bottom of the engineering workspace will show that a debugging session is active with the server components or the client components of the running project.
When the .NET debugger is attached, the system will stop on the defined breakpoints and will stop automatically when any .NET Exception occurs.
Breakpoints, Steps, and Watch
In order to setup a breakpoint, open the desired code, select the line, and press Insert Breakpoint on the toolbar.
When the system stops on a breakpoint, you can perform step by step execution or click the continue button.
In order to inspect local .NET variables, tags, or project objects, select the text in the script editor. When the execution is stopped on a breakpoint, the toolkit will show the current value of the variable.
You can also add .NET variables or project objects to the Watch window. When adding tags or project objects, you need to use the at symbols @, like @tag.tag1. This will allow the system to know it is a project object and not a local .NET variable. Keep in mind that the Watch display is only updated when execution is stopped. If you want to have real-time values for tags and objects, open the PropertyWatch diagnostics tool.
Working with the Script module
Runtime execution
For a detailed understanding of the script execution process on the software framework, refer to the Scripts Runtime Execution and get insights into managing and optimizing scripts' performance.
Monitoring the Script module
The Scripts Monitor feature tracks and assesses script performance, providing crucial insights for optimizing your software platform. Dive into the Monitoring Scripts for an in-depth exploration of script monitoring techniques.
Client-Server Programming
To read more about client-server programming in the software framework context, please explore Client-Server Programming.
Client-Server Data Security
To ensure the security and integrity of your data within the software framework, explore Client-Server Data Security. This resource provides detailed information on safeguarding data exchanges between clients and servers, protecting your project from potential security risks.
Leveraging Built-in Function Libraries
The Script module provides several built-in classes and methods libraries that can greatly streamline your project development process. If you're interested in leveraging the powerful built-in function libraries of software framework, see Built-in Methods and Libraries for detailed documentation.
Troubleshooting and Best Practices
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
Troubleshooting and Common #Issues
The Historian module may encounter some issues in its operation. Here are some common issues and their troubleshooting:
#Issue
Solution
Best Practices and #Recommendations
To ensure the smooth operation of the Historian module, follow these best practices:
#Best practice
Recommendations
: Our code editor supports C#, VB.NET, JavaScript, and Python languages.
Server and Client Domains: Create scripts that execute on the server for global reach or on the client side for local reach.
Events and Scheduling: Tasks and expressions can be triggered by date, time, condition, calendar, tag change, or interval. Execution is distributed among processes, each running in its own application domain, isolated from the real-time database, ensuring maximum system security and performance.
Object Orientation and Solution Object: All solution objects, including tags, datasets, alarms, devices, and communication statuses, are immediately accessible via IntelliSense as native .NET objects. No temporary tags or function calls are required. With a single command, move data from tags to .NET objects and external data tables.
Configure Your Python Interpreter: The Scripts Module delivers exceptional scripting capabilities across various programming languages with seamless integration of Python. You can configure any version of the Python interpreter for each project.
Configuring the Scripts Module
Configuration Workflow
| Scripts Module configuration workflow | ||
|---|---|---|
| Action | Where | Comments |
Manage ScriptClasses | Scripts→Classes | Create or Import you function Library. Learn more at Scripts Classes. |
Manage ScriptTasks | Scripts→Tasks | Create or Import Tasks. Learn more at Scripts Tasks. |
Manage ScriptExpressions | Scripts→Expressions | For simple event or time driven actions, use Expressions. Learn more at Scripts Expressions. |
Manage Script References | Scripts→References. | If you code required their party libraries, include the references. Learn more at Scripts References. |
Working with the Scripts Module
Runtime Execution
The key concept to be aware of regarding the execution of the tasks and expressions defined in the Script Module is that they execute on the server computer.
Only the CodeBehind of the displays is executed on each client computer. The script classes can be consumed by both server and client stations.
Current solutions are prioritizing user interfaces that are portable, meaning the exact same drawing and display configuration can run as a WPF Windows Rich Client or as a web HTML5 page inside a browser. If you intend to run the graphical interface only on WPF Windows and not on web pages, it is possible to enable this in Solution → Settings to allow tasks and expressions to run on the client side.
For complex solutions or very large solutions, it's useful to get a deeper understanding of the Module execution process. Read more at Scripts Module Execution if that is your case.
Script Runtime Attributes
The Namespace Script
Script Runtime Attributes
The Script namespace is the entry point for all objects related to the Scripts module.
The Script.Class object lists all configured tables and its runtime properties. The Script.Task object lists all configured database connections and their runtime properties.
Examples:
Script Task propertiesProperties | ||
|---|---|---|
Property | Type | Description |
| Integer | Number of times the Script Task <Task1> was executed. |
| TimeSpan | The Amount of CPU used the last time the Script Task Task1 was executed. |
→ Read more about Objects and Namespaces.
ModuleScript properties
Property
Type
Description
Script.IsStarted
Boolean
Flag indicating if the module Dataset has started.
Script.OpenStatusMessage
String
Message OK or error when initiating the module.
See Namespaces Reference for the complete list of properties and available methods.
| Anchor | ||||
|---|---|---|---|---|
|
Best Practices and Recommendations
- Code Formatting: Use the 'Format' feature of the editor for more readability.
- Naming Convention: Use a coherent and descriptive naming convention for tasks.
- Task Domain: Select the appropriate domain for each task, considering whether the task is more suitable for client-side or server-side execution. Remember, Client-Side Tasks only applicable to RichClients
- Reusable Code: Use reusable code by creating classes that encapsulate functionalities for use in various parts of the project.
- Library Management: Manage libraries and external components effectively to avoid conflicts and compatibility issues.
- Code Consistency: Maintain code consistency by following best practices and coding conventions.
- Build Before Deployment: Always perform a build operation before deploying a project in a production environment to ensure all scripts are correct and up to date.
Troubleshooting and Common Issues
The Scripts module may encounter some issues in its operation. Here are some common issues and their troubleshooting:
- Build Errors and Warnings: Make sure to check the 'BuildStatus' and 'BuildErrors' tabs to identify and address errors and warnings that arise during the build.
- Code Language: If you change the code language in the code editor, confirm that the code has been correctly converted to the selected language.
- Build Order: Ensure that the build order of the classes is set up correctly to avoid circular dependencies or initialization issues.
- Domain Selection: Ensure that the domain is selected correctly (Client or Server) based on the needs of your project.
- Reference Issues: Make sure that all external references are configured correctly and that there are no compatibility issues or conflicts in the Code Editor.
- Code Formatting: Use the 'Format' feature of the editor for more readability.
- Incremental Compilation Issues: Monitor the incremental compilation process to identify and resolve potential issues that may arise.
- Debugger Setup: Ensure that the debugger setup is correct to allow effective code debugging.
- Breakpoints and Watch Variables: Use breakpoints and watch variables effectively to identify and resolve issues.
In this section:
In this section...| Page Tree | ||||
|---|---|---|---|---|
|
...