Overview
Script References refer to external DLLs (Dynamic Link Libraries) incorporated for compiling scripts or display codes in solution. These references allow users to extend the capabilities of their scripts by leveraging additional functionalities provided by external libraries.
Configuring References
To add a Script Reference, follow the steps below:
- Access Scripts / References.
- Click on the plus icon.
- Browse and select the DLL file that you wish to reference in your solution.
- Input a name, description, and a choose the domain target for the reference.
- Click OK.
Once added, a new row will appear in the References table corresponding to the DLL file you selected.
Script References Configuration Table
The following is a table describing each available property field for Script References:
Property | Description |
|---|---|
Target Domain | Specifies the domain where the DLL will be used (client or server). |
NetAssemblyName | The name of the reference. |
DefaultNamespace | The default namespace used by the DLL. |
Resolved | Indicates whether the reference has been successfully resolved. A checkmark symbol (?) signifies that the DLL import compiled without errors, whereas an 'X' indicates that there were compilation errors. If you encounter an 'X', hover over the line of your Script Reference to view the error code and a description of the problem. |
Portable | Shows if the DLL is portable across different platforms. |
AssemblyPathRuntime | The runtime path of the assembly file used during execution. |
AssemblyPath Macros
When defining the AssemblyPath, the following macros are available:
ConnectionString Macro | |
|---|---|
Macro | Description |
_ExecutionPath_ | Working directory for the solution. Unless otherwise configured, or modified, it is the folder where the solution file is located. |
_ExecutionPathAndName_ | Working directory for the solution, and solution name. |
_GAC_ | Global Assembly Cache, with stores stores assemblies specifically designated to be shared by several applications on the computer |
_ProductPath_ | Path where the product is installed. |
_ProgramFiles_ | Environment.SpecialFolder.ProgramFiles |
_ProgramFilesX86_ | Environment.SpecialFolder.ProgramFilesX86 |
_SolutionName_ | Name of the solution, without path and without extension. Example: Solution1 |
_SolutionPath_ | Path of the solution file. |
_SolutionPathAndName_ | Path of the solution and its name (without extension) |
_Transfers_ | Path of the default folder to transfers, usually the folder Transfers under the product folders in Public Documents. |
_ThirdParty_ | Path for the ThirdParty folder, usually located under MyDocuments/<productName>/ThirdParty |
_WpfControls_ | Path for the WpfControls folder, located in the product Installation folder, sub-directly WpfControls |
Loading and Placing the External DLL
It's necessary to understand the best location to put the external DLLs, and when they are loaded by the platform.
Location of Referenced DLLs
You should avoid using absolute paths, as when you need to move your Solution to other computers, that path may be invalid.
For server-side DLLs, the best location to put the external DLL is the ThirdParty folder created by the platform in your Documents folder after the installation. For Client side DLLs, the best location is WpfControls folder in the product installation folders.
ThirdParty Folder
This folder is to store external server side ThirdParty DLLs. Use the macro _ThirdParty_ at ScriptsReferences to add a reference to those DLLs in your solution.
To add custom C# using statements (or VB Import), use the Namespaces Declarations toolbar icon at the Script CodeEditor. Those DLL can be used on ScriptsTasks and ScriptsClasses of domain Server.
The subfolder SNMP is to add additional MIB files for SNMP communication driver.
WpfControls Folder
This folder is to store external client side WPF Controls DLLs. Use the macro _WpfControls_ at ScriptsReferences to add a reference to those DLLs in your solution
If necessary to add custom C# using statements (or VB Import), use the NamespacesDeclaration toolbar icon at the Script CodeEditor. Those DLLs can be used on Displays and CodeBehind in WPF Displays. Those controls won't be available automatically for SmartClients, for that type Client, it is necessary to create a new manifesto.
if the DLL was created using T.Portable specification, it can also run on Web Pages.
When the DLLs are Loaded
When in Runtime
The DLL is loaded when the Script Module is started. If you need to update the DLL file, you must stop the Script Module and close the Designer (Solution Engineering) so you can replace the DLL file in the folder. After that, you can run the Script Module again, and the DLL will be updated.
Just Using the Designer
The DLL file is loaded when the Edit > Scripts page is opened for the first time. If you open the project, access the Scripts, and add a new DLL in the references for the first time, you can return to Scripts and will be able to use the DLL. However, if you add a DLL in the references, open the Scripts, and only afterward replace or update the DLL file, when you open Scripts again, the script will not be able to find the new modifications of the DLL. You need to close the Designer and open it again, and when you return to Edit > Scripts, the DLL will be updated.
C# Using or VB.NET Import Statements
When using external DLLs it is common to have to add the namespaces of the DLL on your code.
In C#, we refer to that as using, which is equivalent to the VB.NET Import.
Due some optimizations in our Code Editor, you can't add those namespaces directly in the code; you need to use the Add Namespaces button on the top toolbar.
Use this Toolbar command to open the "Namespace Declarations" where you can your namespaces references, whatever you using C# or VB.NET language.
Keeping the Using or Import statement in the code will generate a compilation error.
In this section: