Purpose and Key Concepts

Script Task

Content

Script Class

Content

Script Expressions

Content

How the Script module works

Features highlights

Content

Supported scripting languages

Content

Tasks execution process

Content

Function Libraries in Script Classes

Content

Expressions evaluation and execution

Content

Configuring the Script module

Configuration Workflow

Content

Creating and managing Script Tasks

Content

Pre-defined Tasks

Content

Adding and editing Script Classes

Content

Pre-defined Classes

Content

Creating and Utilizing Expressions

Content

Managing External References

Content

Programming with the Code Editor

Productivity enhancements

Content

Themes and user preferences

Content

Intellisense support

Content

Using the TK Toolkit Namespace

Content

Scripts compilation

Content

Incremental compiling

Content

Incorporating external assemblies

Content

Debugging and error Handling

Content

Leveraging the .NET Debugger

Content

Working with the Script module

Runtime execution

Content

Scripts module integrations

Content

Project Objects and Namespaces

Content

Displays, Code Behind

Content

Alarms, Notifications Event Handler

Content

Historian, Custom Retrieval and Archiving

Content

Utilizing ServerMain Class Entry Points

Content

Advanced options

Content

Troubleshooting and best practices

Common issues and solutions

Content

Best practices and recommendations

Content

Script module runtime attributes

Content

New Organization to this module:

About the Script module

Purpose and Key Concepts
* Script Task
* Script Class
* Script Expressions

How the Script module Works
* Features highlights
* Supported Scripting Languages
* Tasks Execution Process
* Function Libraries in Script Classes
* Expressions Evaluation and Execution

Configuring the Script module
* Configuration Workflow
* Creating and Managing Script Tasks
** Pre-defined Tasks
* Adding and Editing Script Classes
* Pre-defined Classes
* Creating and Utilizing Expressions
* Managing External References

Programming with the Code Editor
* Productivity Enhancements
** Themes and User Preferences
** Intellisense Support
** Using the TK Toolkit Namespace
* Scripts Compilation
** Incremental Compiling
** Incorporating External Assemblies
* Debugging and Error Handling
** Leveraging the .NET Debugger

Working with the Script module
* Runtime Execution
* Integration with Other modules
** Project Objects and Namespaces
** Displays, Code Behind
** Alarms, Notifications Event Handler
** Historian, Custom Retrieval and Archiving
** Utilizing ServerMain Class Entry Points
* Advanced Features and Options

Troubleshooting and Best Practices
* Common Issues and Solutions
* Best Practices and Recommendations
* Script module Runtime Attributes

Text for about: 

The Script Module is a powerful feature in Tatsoft FrameworX and FactoryStudio that enables users to execute custom code and extend the functionality of the entire platform. With support for multiple programming languages, including C#, VB.NET, Python, and JavaScript, the Script Module allows users to develop high-performance, server-side, and client-side scripts that can be easily integrated into their projects.

What is the Script Module

<< NOTE: When doing the new rogation this WHAT IS content shall be moved the section title Features Highlights, under the section How the script module Works

The Script Module brings to the Project configuration the ability to execute custom code and extend the functionality of the entire platform.

Programming languages included are C#, VB.NET, Python and JavaScript. 

The Script Module feature set includes: 

• 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.

Delivers high-performance server-side and client-side scripting capability. Programming languages include C#, VB .NET, Python, and JavaScript. Easily create multi-threading applications with parallel execution for the task and add references to externally developed classes.

Key Concepts

Script Task

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 Class

A Script Class is a library of functions and methods that you can consume on 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

When you need to execute one line of code in a reaction 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 Task.

Configuring Tasks

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:

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 Script Classes

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 - Methods library available for all server tasks.
• ClientMain - Methods library available for all clients.

Creating and Editing Script Classes

To configure Script Classes:

• Go to Edit → Scripts → Classes.
• Select a task name, or select the insertion row (first blank row) to create a new task.
• Enter or edit fields as needed.

Working with the Code Editor

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.

IntelliSense

InteliSense 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.

Editing Code 

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 Configuring Tasks or Configuring Script Classes 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.

Using the .NET Debugger

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.

Configuring Expressions

Overview

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. 

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.

In this .NET method, all three parameters are evaluated regardless of the condition. For instance, if you have IIF (tag.A = 1, script.class.client.Func1(), script.class.client.Func2()), both Func1 and Func2 will always be executed. Only the return value will be different based on the value of tag.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())

Only the Func1() or Func2() will be executed, according the value of Tag.A

The 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.

Scripts Compiling

Incremental Compiling

All C# and VB.NET scripts are automatically compiled in background as you create them, without the needs of expressly request it.

For performance optimization, only the scripts you just changed are compiled, not the entire project. This method of compiling only the affected parts  -  not the entire system again  -  is called Increment Compiling.

This concept is Important to understand why their the command of Build for a Project. The Build Command will recompile all the scripts on the entire Project. <<<<. please check this paragraph. the first info is a little confusing >>>>

It is recommend to execute a Build before deploying the project for Production. When upgrading or Importing Projects it is mandatory to perform a Project Build Operation. 

Using External Assemblies

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. 

The TK 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.

The Script Namespace

The namespace Script is the entry point for all objects related to the Scripts Module.

The Script.Task object lists all configured database connections and their runtime properties.

The Script.Class object lists all configured tables and its runtime properties.

Examples:

In this section...