ExecuteCSharp@1
Node ExecuteCSharp@1 executes inline C# code with typed arguments and returns a typed result. This node allows you to perform complex calculations, string manipulations, and data transformations using the full power of C#.
Adapter Prerequisites
- General availability: All adapters support this node type.
Node Configuration
For fields targetPath, targetValueWriteMode, and targetValueKind, see Overview.
transformations:
- type: ExecuteCSharp@1
targetPath: $.calculatedValue # Path where the result will be stored
code: "Math.Round(price * (1 + taxRate), 2)" # C# code to execute
returnType: DOUBLE # Expected return type
timeoutMs: 5000 # Execution timeout in milliseconds
arguments: # Arguments to pass to the script
- name: price # Variable name in C# code
valuePath: $.basePrice # JSON path to get the value
dataType: DOUBLE # Data type of the argument
- name: taxRate # Variable name in C# code
value: 0.19 # Fixed value (alternative to valuePath)
dataType: DOUBLE # Data type of the argument
usings: # Additional using statements
- "System.Linq"
- "System.Text.RegularExpressions"
Parameters
Required Parameters
| Parameter | Type | Description |
|---|---|---|
code | string | The C# code to execute. Can be an expression or contain return statements |
returnType | enum | Expected return type: STRING, INT, INT64, BOOLEAN, DOUBLE, DATETIME |
targetPath | string | The JSON path where the result will be stored |
Optional Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
arguments | array | [] | List of arguments to pass to the script |
timeoutMs | integer | 5000 | Execution timeout in milliseconds |
usings | array | [] | Additional using statements for the script |
targetValueWriteMode | enum | - | How to write the value (see Overview) |
targetValueKind | enum | - | The kind of target value (see Overview) |
documentMode | enum | - | Document mode for the operation (see Overview) |
Argument Configuration
Each argument in the arguments array has the following properties:
| Property | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Variable name to use in the C# script |
dataType | enum | Yes | Data type: STRING, INT, INT64, BOOLEAN, DOUBLE, DATETIME |
valuePath | string | No | JSON path to get the value from data context |
value | any | No | Fixed value to use (alternative to valuePath) |
optional | boolean | No | true when valuePath may be absent: a missing path is not reported as a warning (default: false) |
defaultValue | any | No | Value the script receives when valuePath is missing or holds null (default: none, the script gets the type's default). Must be convertible to dataType |
Note: Each argument must have either valuePath or value specified, but not both.
Missing Argument Paths
When the valuePath of an argument does not exist in the data context, the script receives defaultValue. Without a defaultValue the script variable gets its type's default: null for STRING and the array types, 0, false or DateTime.MinValue for INT, INT64, DOUBLE, BOOLEAN and DATETIME (these variables are not nullable, so compare with the default, e.g. dueDate == DateTime.MinValue). The node does not fail.
- Optional argument (
optional: true): nothing is logged at warning level, only a debug line per record. Use it for fields that are legitimately absent on some records. - Non-optional argument: the node reports the missing path once per pipeline execution as one warning with the number of records it was missing in, for example
ExecuteCSharp argument 'dueDate': path '$.key.dueDate' was not found in 1234 record(s) of this execution, null was used.The per-record detail is logged at debug level. Before this change one warning was logged per record, which inside aForEach@1produced one line per item. - A path that exists with value null is not reported; the script receives
defaultValueor the type's default, as for a missing path. defaultValueis converted todataTypeon every execution, also when the path exists. A value that cannot be converted (for exampleabcforINT) fails the node with a message naming the argument.
arguments:
- name: dueDate
valuePath: $.key.Attributes.DueDate
dataType: DATETIME
optional: true # absent on many records: no warning
- name: comment
valuePath: $.key.Attributes.Comment
dataType: STRING
optional: true
defaultValue: "" # the script gets "" instead of null (STRING default)
How It Works
- Argument Processing: The node extracts values from the data context using JSON paths or uses fixed values
- Type Conversion: All arguments are converted to their specified data types
- Script Compilation: The C# code is compiled with the arguments as variables
- Execution: The compiled script is executed with the specified timeout
- Result Conversion: The return value is converted to the specified return type
- Caching: Compiled scripts are cached for better performance on repeated executions
Supported Data Types
| Type | C# Type | Description |
|---|---|---|
STRING | string | Text values |
INT | int | 32-bit integers |
INT64 | long | 64-bit integers |
BOOLEAN | bool | Boolean values |
DOUBLE | double | Floating-point numbers |
DATETIME | DateTime | Date and time values |
Code Syntax
- Expression Mode: If the code doesn't contain a
returnstatement, it's treated as an expression - Statement Mode: If the code contains
returnstatements, it's executed as-is - Variables: All arguments are available as typed variables in the script
- Using Statements: Default includes
SystemandSystem.Math, additional can be specified
Error Handling
The node will throw an error if:
- The C# code has compilation errors
- Script execution times out
- Type conversion fails
defaultValuecannot be converted to the argument'sdataType
A missing argument path is not an error; see Missing Argument Paths.
Examples
Example 1: Mathematical Calculation
transformations:
- type: ExecuteCSharp@1
targetPath: $.totalPrice
code: "Math.Round(basePrice * quantity * (1 + taxRate), 2)"
returnType: DOUBLE
arguments:
- name: basePrice
valuePath: $.price
dataType: DOUBLE
- name: quantity
valuePath: $.qty
dataType: INT
- name: taxRate
value: 0.19
dataType: DOUBLE
Input:
{
"price": 29.99,
"qty": 3
}
Output:
{
"price": 29.99,
"qty": 3,
"totalPrice": 107.17
}
Example 2: String Manipulation
transformations:
- type: ExecuteCSharp@1
targetPath: $.formattedName
code: |
if (string.IsNullOrEmpty(middleName))
return $"{firstName} {lastName}".ToUpper();
else
return $"{firstName} {middleName[0]}. {lastName}".ToUpper();
returnType: STRING
arguments:
- name: firstName
valuePath: $.person.first
dataType: STRING
- name: middleName
valuePath: $.person.middle
dataType: STRING
- name: lastName
valuePath: $.person.last
dataType: STRING
Input:
{
"person": {
"first": "John",
"middle": "Michael",
"last": "Doe"
}
}
Output:
{
"person": {
"first": "John",
"middle": "Michael",
"last": "Doe"
},
"formattedName": "JOHN M. DOE"
}
Example 3: Date Calculations
transformations:
- type: ExecuteCSharp@1
targetPath: $.daysUntilDue
code: "(dueDate - DateTime.Now).Days"
returnType: INT
arguments:
- name: dueDate
valuePath: $.invoiceDueDate
dataType: DATETIME
Input:
{
"invoiceDueDate": "2024-12-31T00:00:00Z"
}
Output:
{
"invoiceDueDate": "2024-12-31T00:00:00Z",
"daysUntilDue": 87
}
Example 4: Complex Logic with LINQ
transformations:
- type: ExecuteCSharp@1
targetPath: $.isValidEmail
code: |
return !string.IsNullOrEmpty(email) &&
email.Contains("@") &&
email.Split('@').Length == 2 &&
!email.StartsWith("@") &&
!email.EndsWith("@");
returnType: BOOLEAN
usings:
- "System.Linq"
arguments:
- name: email
valuePath: $.contactEmail
dataType: STRING
Input:
{
"contactEmail": "user@example.com"
}
Output:
{
"contactEmail": "user@example.com",
"isValidEmail": true
}
Example 5: Prime Number Check
transformations:
- type: ExecuteCSharp@1
targetPath: $.isPrime
code: |
if (number <= 1) return false;
if (number <= 3) return true;
if (number % 2 == 0 || number % 3 == 0) return false;
for (int i = 5; i * i <= number; i += 6)
{
if (number % i == 0 || number % (i + 2) == 0)
return false;
}
return true;
returnType: BOOLEAN
arguments:
- name: number
valuePath: $.testNumber
dataType: INT
Input:
{
"testNumber": 97
}
Output:
{
"testNumber": 97,
"isPrime": true
}
Example 6: Conditional Logic
transformations:
- type: ExecuteCSharp@1
targetPath: $.riskLevel
code: |
if (score >= 80) return "LOW";
else if (score >= 60) return "MEDIUM";
else if (score >= 40) return "HIGH";
else return "CRITICAL";
returnType: STRING
arguments:
- name: score
valuePath: $.creditScore
dataType: INT
Input:
{
"creditScore": 65
}
Output:
{
"creditScore": 65,
"riskLevel": "MEDIUM"
}
Use Cases
- Mathematical Calculations: Complex formulas, financial calculations, statistical operations
- String Processing: Text formatting, validation, parsing, concatenation
- Date/Time Operations: Date arithmetic, formatting, timezone conversions
- Conditional Logic: Business rules, data validation, classification
- Data Transformation: Type conversions, value mapping, normalization
- Custom Algorithms: Implementing specific business logic that can't be achieved with standard nodes
Notes
- Performance: Scripts are compiled once and cached for subsequent executions
- Security: Scripts run in a sandboxed environment with limited access
- Timeout: Always specify appropriate timeout values to prevent infinite loops
- Memory: Be mindful of memory usage in complex calculations
- Error Handling: Use try-catch blocks in your C# code for graceful error handling
- Null Safety: The node automatically handles null values according to the
#nullable disabledirective - Type Safety: All arguments are strongly typed and validated before script execution