Custom Node Types

Custom node types are used to extend the orchestrated nodes of the rule engine. Users create nodes, maintain processing logic, and define parameters; after successful compilation, they can be dragged into the rule flow for use.

Before creating a node

First, look at the terminology

Page Entry

After logging into TGateway Web, click the “Develop Configuration → Custom Node” menu on the left.

Prerequisites

• Define the inputs, outputs, error handling, and permitted side effects before writing the node.
• Choose a name and category distinguishable from loaded nodes, and identify the flows that will consume it.
• Export the affected flows and arrange a verification window before changing a node used in production.

Configure and compile the node

Page Structure

List Field

Create a new node

Click the ‘Add Node’ button at the top right of the list to open the “New Custom Node” pop-up.

After clicking “OK,” the system will create a node and automatically enter the node editor.

Node Editor

The node editor includes the top operation bar, code editing area, and bottom information panel.

Type this. to complete user methods, fields, and generated parameter properties in the node. Signature help follows the call’s parentheses and commas. Add /// XML comments to describe methods, fields, and properties in suggestions and hover. The default service is https://roslyn.thingsgateway.cn; a self-hosted Studio is also supported. See Code Completion, Documentation, and Diagnostics.

Node Information

The “Node Information” tab is used to maintain basic information.

Parameter Definition

The “Parameter Definition” tab maintains three types of parameters: input, output, and input/output. Parameter definitions affect node connections and data transfer in the rule flow.

The Web editor offers Int16, Int32, Int64, UInt16, UInt32, UInt64, Byte, Float, Double, Decimal, Boolean, String, Object, and DateTime. Define the type separately for each input, output, and input/output port. Renaming a parameter also requires updating its code references and every consuming flow.

Initial Value Expression is C#, for example Decimal 1m + 1m. An explicit instance input or upstream connection overrides that starting value. Validate integer ranges, use an explicit timezone for dates, and preserve object structure. Event parameters have no state initial value.

Loaded-node details show state/event semantics, nullability, array and unit contracts, and node configuration parameters without ports. Use explicit converters for mismatched semantics or numeric types. Reordering parameters preserves named-port identity; renaming requires updating code and consuming flows before validation.

Compilation Log

After clicking “Compile and Save” at the top, the “Compilation Log” at the bottom will display the saving and compilation process.

When a compilation error occurs, first handle the first red error; Click the error item to locate the corresponding code location.

Node saved successfully means the draft was saved; compilation can still fail afterward. Reopen a failed draft to edit it while the previous valid version remains available. After successful compilation, check Loaded Nodes, then reload and verify consuming flows as described below.

If another editor has changed the node, preserve your draft before reading the current revision and comparing changes. Do not overwrite another maintainer’s update.

Common Operations

Verify node behavior

Initial values, state, and event ports

Enter only class members in the Web node editor. Do not wrap them in a complete class or redeclare properties already defined in the parameter table. Compile complete C# node classes through the Full Source script type in Script Management. See Custom Node Development for examples.

Inputs receive upstream values; without a connection use the instance input. State outputs propagate only when their value changes by default. Event ports represent occurrences and can propagate equal payloads repeatedly; do not enter state initial values for event parameters. For inputs 10.1 and 10.2 both rounded to 10, a state receiver may run once while an event receiver runs twice. Check execution and downstream counts.

Test a conversion node in a flow

1. Define a Decimal input Input and output Output in the Web node. Use gain 2 and offset 5; see the Web node example for member code.
2. Compile and save, then confirm the name, category, and ports in Loaded Nodes.
3. Create a disabled test flow connecting a scoped variable notification, numeric extraction, this node, and a downstream receiver.
4. Save and enable it. Input 10 should produce 25, then 20 should produce 45. Check the node output, downstream input, and execution result separately.
5. If the node has state or counters, verify their initial state after reenabling. Design explicit persistence if values must survive restarts.

Verify a revised node

1. Compile/save and check name, category, and port types in Loaded Nodes.
2. Use a disabled test flow with scoped input, numeric extraction, this node, and a downstream receiver. For gain 2 and offset 5, verify 10 → 25 and 20 → 45.
3. After same-name recompilation, existing flows can retain old instances. Save/reload the consumer and test an input distinguishing the formulas.
4. Recheck every connection after parameter changes. Disabling stops consumption; reenabling creates fresh state and counters unless persistence is explicitly designed.
5. Remove all flow references before deletion. A disabled flow still contains references.

Use the node in production after its output values, parameter types, and error handling match the design.

Troubleshooting and maintenance

Related Links

• Rule Engine
• Custom Node Development Notes
• Script Management
• Collection Configuration