Page History

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

Configuring References

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.

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 or Client
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:

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

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

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 (?)
• 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

In this section...