Page History

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

Overview

Script References allow you to:

• Add external .NET assemblies to your solution
• Extend functionality beyond built-in namespaces
• Use third-party libraries in Scripts and Displays
• Share custom components across solutions

FrameworX includes many .NET namespaces by default. Script References are needed only when you require additional external assemblies not included in the platform.

Configuring References

To add a Script Reference

:

Access
1. Navigate to Scripts
/
2. → References
.
4. Click
on the 
5. the plus icon
.
7. Browse and select the DLL file
that you wish to reference in your solution.
8. Input a name, description, and a choose the domain target for the reference.
9. Click OK.

Once added, a new row will appear in the References table corresponding to the DLL file you selected. 

2. Configure:
   • Name: Reference identifier
   • Description: Purpose of the library
   • Target Domain: Server or Client
3. Click OK

The new reference appears in the References table.

Configuration Properties

Script References Configuration Table

Property	Description
Target Domain

Specifies the domain where

Where the DLL

will be used

executes (

client

Server or

server

Client)

.

NetAssemblyName

The

Reference name

of

in the

reference.

solution

DefaultNamespace

The default

Primary namespace

used by

of 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:

Assembly Path Macros

Use these macros instead of absolute paths for portability:

Additional Macros

Loading and Placing External DLLs

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.

DLL Placement Best Practices

ThirdParty Folder

Location: MyDocuments/[ProductName]/ThirdParty

• Store server-side external DLLs
• Use macro: _ThirdParty_
• Domain: Server
• Usage: Script Tasks, Script Classes (Server)

Special Subfolder:

• /SNMP - Additional MIB files for SNMP driver

WpfControls Folder

Location: [InstallPath]/WpfControls

• Store client-side WPF control DLLs
• Use macro: _WpfControls_
• Domain: Client
• Usage: Displays, Code Behind

<ac:structured-macro ac:name="info"> ac:rich-text-body SmartClient Note: WPF controls require additional manifest configuration for SmartClient deployment. Controls created with T.Portable specification can run on Web Pages. </ac:rich-text-body> </ac:structured-macro>

Using Referenced Assemblies

1. Add the Reference

Go to Scripts → References and add the DLL location.

2. Add Namespace Declarations

Open Code Editor and click the Namespace Declarations button to add namespaces.

<ac:structured-macro ac:name="warning"> ac:rich-text-body Important: Never put using (C#) or Import (VB.NET) statements directly in code. Always use the Namespace Declarations dialog. Direct statements will cause compilation errors. </ac:rich-text-body> </ac:structured-macro>

3. Use in Code

csharp

// After adding reference and namespace declaration
// You can use types from the external assembly
var processor = new ExternalLibrary.DataProcessor();
var result = processor.Process(data);

DLL Loading Behavior

Runtime Loading

• DLLs load when Script Module starts
• To update DLL:
  1. Stop Script Module
  2. Close Designer
  3. Replace DLL file
  4. Restart Script Module

Designer Loading

• DLLs load when Scripts page first opens
• To update DLL after initial load:
  1. Close Designer completely
  2. Replace DLL file
  3. Reopen Designer
  4. Navigate to Scripts

<ac:structured-macro ac:name="note"> ac:rich-text-body The platform caches loaded assemblies for performance. Complete Designer restart is required to reload updated DLLs. </ac:rich-text-body> </ac:structured-macro>

Namespace Declarations Dialog

Access via Code Editor toolbar button:

This dialog allows you to:

• View default included namespaces
• Add namespaces from referenced assemblies
• Add system namespaces not included by default
• Manage both C# using and VB.NET Import statements

The declarations apply to:

• Current Script Class or Task (when editing scripts)
• Current Display (when editing Code Behind)

Troubleshooting

Reference Not Resolved (Red X)

• Hover over row to see error details
• Verify DLL targets correct .NET version
• Check assembly dependencies are available
• Ensure path macro is valid

Types Not Found in Code

• Confirm reference shows Resolved (?)
• Add namespace via Namespace Declarations
• Verify Target Domain matches usage location
• Check DLL compatibility with solution framework

DLL Updates Not Reflected

• Close Designer completely
• Replace DLL file
• Reopen Designer and Scripts page
• For runtime: Stop/restart Script Module

Path Issues When Moving Solutions

• Use macros instead of absolute paths
• Ensure DLLs exist in standard folders
• Copy ThirdParty folder with solution

Best Practices

1. Always use path macros - Never hardcode absolute paths
2. Match target frameworks - Ensure DLL compatibility
3. Organize by domain - Server DLLs in ThirdParty, Client in WpfControls
4. Document dependencies - Note required DLLs in solution documentation
5. Version control - Include referenced DLLs in source control
6. Test after updates - Verify functionality when updating DLLs
7. Use Namespace Declarations - Never add using/import statements directly in code

In this section...

Namespace Declarations

C# Using or VB.NET Import Statements

When using external DLLs it is common 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.Image Removed

Use this Toolbar command to open the "Namespace Declarations" where you can your namespaces references, whatever you using C# or VB.NET language. 

In this section: