Debug and troubleshoot your scripts.

Reference → Code → Code Library → Debugging

This document explains how to debug script code using the Microsoft Visual Studio environment instead of our internal debugging tools.

This approach is recommended for multiplatform solutions, because the Designer runs on .NET Framework 4.8, while the multiplatform solution runs on .NET 8.0. As a result, runtime debugging must be performed outside of FrameworX, and the procedure described here is the recommended method.

However, the same process can also be used for Windows-only solutions.

Debug using Microsoft Visual Studio

Requirements

  • Microsoft Visual Studio
  • .NET 8.0 for multiplatform solution or .NET Framework 4.8 for windows-only solution.

Debug Information

Before attaching Visual Studio, ensure the following conditions are met for each display or script you want to debug:

1. Debug Info checkbox: The Debug Info checkbox must be enabled in the display/script settings. This causes the output to be compiled as Debug. If it is not enabled, the output will be Release and debugging will not be possible.

2. User access permission: The currently logged-in engineering user must have access permission to the display or script. Even if the Debug Info checkbox is enabled, compilation will produce Release output if the user lacks the required permission.

3. Content Hidden plugin setting: If Content Hidden is checked on the plugin, compilation is always Release, regardless of the Debug Info checkbox or user permissions.

4. Attach Requirement: To attach an external Visual Studio debugger, ALL scripts and/or displays must be compiled as Debug, no exceptions.

  • Server-side debugging (TServer / TRunModule): Every ScriptTask and ScriptClass with Domain = Server must be compiled as Debug.
  • Client-side debugging (TRichClient): Every ScriptTask, ScriptClass, and Display must be compiled as Debug.


Scripts and Displays

A single script or display compiled as Release, even if not currently in use, will prevent the VS debugger from attaching. The debugger will be blocked or the RichClient will crash on attach attempt.


Procedure

1 - Run your solution

2 - Open Microsoft Visual Studio.

3 - Go to Debug > Attach to Process….

4 - In the list, select the relevant Process (see guidance below).

5 - Click Attach. Visual Studio is now attached to the running process.

6 - In Solution Explorer, you will see a tree of multiple components, for example:

If you do not see the script you need, you must first trigger/run that script in the application. Once it is executed, it will appear in the list.

Solution
+-- External Sources
    +-- Modules without sources
        |-- Anonymously Hosted DynamicMethod
        |-- Class_0_638948088211382802_0
        |-- Class_2_639003032851421397_0
        |-- Flee.dll
        |-- MessagePack.Annotations.dll
        +-- MessagePack.dll

In this example, we are debugging a Class, so you can see Class_0 and Class_2.
The number corresponds to the Class ID. To confirm the mapping, go to Scripts > Class and check the ID column.

7 - Right-click the target class (e.g. Class_2_639003032851421397_0) and select Decompile Source to Symbol File.

8 - The class will now be moved under External Sources, and the tree will look similar to:

Solution
+-- External Sources
    |-- Class_2_639003032851421397_0
    |   +-- Scripts
    |       +-- Class_Class1.cs
    +-- Modules without sources
        |-- Anonymously Hosted DynamicMethod
        |-- Class_0_638948088211382802_0
        |-- Flee.dll
        |-- MessagePack.Annotations.dll
        +-- MessagePack.dll

9 - You can now open the decompiled .cs file, set breakpoints, and debug the code in real time.

Process

  • If your solution is multiplatform, you must attach to the dotnet.exe process. You will likely see multiple processes with this name, so use the Command Line column to identify which one corresponds to the script you want to debug.

  • If your solution is Windows-only, you must attach to the TRunModule.exe process. Again, there may be multiple instances, so check the Command Line to determine which one is associated with the script.

If the script module is running inside the TServer process, you must attach to TServer.exe instead of the processes mentioned above. Check that in Solution > Settings.

  • If the script is running on the client side, you must attach to the TRichClient.exe process.

Process example:

“<processName>” "<ProductPath>\fx-10\net8.0\TRunModule.dll" /module:t.modules.Script /ip1:127.0.0.1 /port1:3101 /connectiontimeout:60 /profile:0

In this section...