Scripts References Reference

Review object references from scripts.

Reference → Modules → Scripts → UI → Code Editor | Classes | Expressions | Monitor | References | Tasks 

Configuring References

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

Assemblies Referenced by Default

The assemblies available to scripts without a Script Reference depend on the script target:

Any assembly not referenced by default for the script target must be added as a Script Reference, including assemblies that are part of .NET. For example, System.Management (WMI) is available by default only to Server scripts on .NET Framework 4.8. To use it in Server scripts on .NET 10 or in Client scripts, add _ProductPath_System.Management.dll as a Script Reference with the matching Target Domain. System.Management works only on Windows: in a Multi-Platform solution running on Linux, it compiles but fails at runtime.

To add a Script Reference:

1. Navigate to Scripts → References
2. Click the plus icon
3. Browse and select the DLL file
4. Configure:
   • Name: Reference identifier
   • Description: Purpose of the library
   • Target Domain: Server, Client, ServerAndClient, or Disabled
5. Click OK

The new reference appears in the References table.

Configuration Properties

Assembly Path Macros

Use these macros instead of absolute paths for portability:

Folder macros already end with a path separator, so the rest of the path follows the macro directly, without a slash. Examples for a default installation and a solution saved as D:\Projects\Plant1\Plant1.dbsln:

Everything after the macro is part of the path, including version folders. If the DLL is moved to a folder with a different name (for example, MyLib.1.0.1 instead of MyLib.1.0.0), the reference no longer resolves. When you add a DLL with the plus icon, the Designer writes the macro automatically if the file is inside the installation folder or the solution folder, so re-adding the reference is the safest way to fix a wrong path.

Additional Macros

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
  
  

Multi-Engineering (Solution Server)
When editing a solution remotely via Solution Server, compilation runs on the client (Designer) machine, not on the server. The server only executes the compiled output. This means the DLL must be present on both machines: on the client so the Designer can compile, and on the server so the runtime can load it. Use path macros (such as _ThirdParty_ or _SolutionPath_) and place the DLL in the same relative folder on both machines. This ensures the reference resolves correctly in both environments.
The same applies to the .NET runtime: scripts compile to .NET Framework 4.8 in Windows solutions and to .NET 10 in Multi-Platform solutions (FrameworX 10.1.5 and later), so a Multi-Platform solution also needs the .NET 10 Desktop Runtime on the Designer machine. See Script Compilation Target.
Note: the Verify References check also runs on the client side and reflects client-side accessibility only.

Remote Clients

Each process resolves AssemblyPathRuntime against its own file system, and Target Domain decides which process loads the row: the server-side Script module skips Client rows, and the client-side Script module skips Server rows. A Client DLL must therefore be present on every machine that runs a Client, not only on the server.

Exception: assemblies that are part of .NET Framework and registered in the Windows Global Assembly Cache, such as System.Management, do not need to be copied to client machines. On Rich Client and Smart Client, .NET loads the version installed with Windows, whatever path is configured.

Rich Client has one fallback that reaches a local installation folder, and it is tied to WpfControls: when the resolved path is absolute, contains a \WpfControls\ folder segment, and the file is not found there, the client retries the same file name in the WpfControls folder of its own installation. A path without that segment — a DLL kept in a subfolder of the solution, for example — gets no such fallback.

To load a Client DLL on Rich Clients running on other machines, place the DLL in the WpfControls folder of the FrameworX installation on each of those machines.

SmartClient resolves differently: it looks for the file name in its local WpfControls folder, and otherwise downloads it from <SmartClient URL>/WPFControls/.

An AssemblyPathRuntime that starts with http:// or https:// is downloaded before loading, into a WPFControlsCache folder created next to the running executable.

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.

3. Use in Code

// 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

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)

Best Practices

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

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 (green check)
• Add namespace via Namespace Declarations
• A namespace declaration alone does not add the assembly to the build. If the assembly is not referenced by default for the script target (see Assemblies Referenced by Default), add it in Scripts → References
• Verify Target Domain matches usage location
• Check DLL compatibility with solution framework

Build Errors Even Though the Reference Looks Resolved

Symptoms: the script fails with errors such as CS0103 (the name does not exist), CS0246 (type or namespace not found) or CS0122 (inaccessible due to its protection level) on types from the referenced DLL, even when using the full namespace.

• The build includes a reference only when its Target Domain matches the domain of the Script Class or Task being compiled. A reference set to Server is not available to a Client class, and the reverse.
• If the resolved path does not exist, the Designer looks for the same file name directly in the _ProductPath_ folder (for example, C:\Program Files\Tatsoft\FrameworX\fx-10\MyLib.dll) and directly in the _SolutionPath_ folder (for example, D:\Projects\Plant1\MyLib.dll), without subfolders. If the file is not found there either, the reference is left out of the build without a separate message.
• A green check in Resolved may be outdated (for example, after copying the solution to another computer or moving the DLL). Click Verify References to check the path again on the current computer.

DLL Updates Not Reflected

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

Client DLL Loads on the Server but Not on Remote Clients

• The Script module writes Build References :: Failed openning '<path>': <error> to the trace of the process that tried to load it — the path shown is the fully resolved path on that machine, after macro expansion
• Verify that path exists on the client machine, not only on the server
• Only a path containing a \WpfControls\ segment falls back to the client's local installation folder — see Remote Clients above
• A reference downloaded over http/https logs Build References :: Failed downloading '<url>': <error> instead

Path Issues When Moving Solutions

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

In this section...