ExecuteCSharp@1

Der Node ExecuteCSharp@1 führt eingebetteten C#-Code mit typisierten Argumenten aus und liefert ein typisiertes Ergebnis zurück. Mit diesem Node können Sie komplexe Berechnungen, String-Manipulationen und Datentransformationen mit der vollen Mächtigkeit von C# durchführen.

Adapter-Voraussetzungen

• Allgemeine Verfügbarkeit: Alle Adapter unterstützen diesen Node-Typ.

Node-Konfiguration

Für die Felder targetPath, targetValueWriteMode und targetValueKind siehe Überblick.

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"

Parameter

Erforderliche Parameter

Parameter	Typ	Beschreibung
code	string	Der auszuführende C#-Code. Kann ein Ausdruck sein oder return-Anweisungen enthalten
returnType	enum	Erwarteter Rückgabetyp: STRING, INT, INT64, BOOLEAN, DOUBLE, DATETIME
targetPath	string	Der JSON-Pfad, unter dem das Ergebnis gespeichert wird

Optionale Parameter

Parameter	Typ	Standard	Beschreibung
arguments	array	[]	Liste der an das Skript zu übergebenden Argumente
timeoutMs	integer	5000	Ausführungs-Timeout in Millisekunden
usings	array	[]	Zusätzliche using-Anweisungen für das Skript
targetValueWriteMode	enum	-	Wie der Wert geschrieben wird (siehe Überblick)
targetValueKind	enum	-	Die Art des Zielwerts (siehe Überblick)
documentMode	enum	-	Dokumentmodus für die Operation (siehe Überblick)

Argument-Konfiguration

Jedes Argument im Array arguments hat die folgenden Eigenschaften:

Eigenschaft	Typ	Erforderlich	Beschreibung
name	string	Ja	Variablenname zur Verwendung im C#-Skript
dataType	enum	Ja	Datentyp: STRING, INT, INT64, BOOLEAN, DOUBLE, DATETIME
valuePath	string	Nein	JSON-Pfad, um den Wert aus dem Data Context zu holen
value	any	Nein	Fester Wert (Alternative zu valuePath)

Hinweis: Jedes Argument muss entweder valuePath oder value angeben, aber nicht beides.

Funktionsweise

1. Argumentverarbeitung: Der Node extrahiert Werte über JSON-Pfade aus dem Data Context oder verwendet feste Werte
2. Typkonvertierung: Alle Argumente werden in ihre angegebenen Datentypen konvertiert
3. Skript-Kompilierung: Der C#-Code wird mit den Argumenten als Variablen kompiliert
4. Ausführung: Das kompilierte Skript wird mit dem angegebenen Timeout ausgeführt
5. Ergebniskonvertierung: Der Rückgabewert wird in den angegebenen Rückgabetyp konvertiert
6. Caching: Kompilierte Skripte werden für bessere Performance bei wiederholten Ausführungen zwischengespeichert

Unterstützte Datentypen

Typ	C#-Typ	Beschreibung
STRING	string	Textwerte
INT	int	32-Bit-Ganzzahlen
INT64	long	64-Bit-Ganzzahlen
BOOLEAN	bool	Boolesche Werte
DOUBLE	double	Gleitkommazahlen
DATETIME	DateTime	Datums- und Zeitwerte

Code-Syntax

• Ausdrucksmodus: Enthält der Code keine return-Anweisung, wird er als Ausdruck behandelt
• Anweisungsmodus: Enthält der Code return-Anweisungen, wird er unverändert ausgeführt
• Variablen: Alle Argumente stehen als typisierte Variablen im Skript zur Verfügung
• Using-Anweisungen: Standardmäßig sind System und System.Math enthalten, weitere können angegeben werden

Fehlerbehandlung

Der Node löst einen Fehler aus, wenn:

• Der C#-Code Kompilierungsfehler aufweist
• Die Skriptausführung das Timeout überschreitet
• Die Typkonvertierung fehlschlägt
• JSON-Pfade nicht existieren (sofern der Wert nicht null ist)

Beispiele

Beispiel 1: Mathematische Berechnung

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

Eingabe:

{
  "price": 29.99,
  "qty": 3
}

Ausgabe:

{
  "price": 29.99,
  "qty": 3,
  "totalPrice": 107.17
}

Beispiel 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

Eingabe:

{
  "person": {
    "first": "John",
    "middle": "Michael",
    "last": "Doe"
  }
}

Ausgabe:

{
  "person": {
    "first": "John",
    "middle": "Michael",
    "last": "Doe"
  },
  "formattedName": "JOHN M. DOE"
}

Beispiel 3: Datumsberechnungen

transformations:
- type: ExecuteCSharp@1
  targetPath: $.daysUntilDue
  code: "(dueDate - DateTime.Now).Days"
  returnType: INT
  arguments:
    - name: dueDate
      valuePath: $.invoiceDueDate
      dataType: DATETIME

Eingabe:

{
  "invoiceDueDate": "2024-12-31T00:00:00Z"
}

Ausgabe:

{
  "invoiceDueDate": "2024-12-31T00:00:00Z",
  "daysUntilDue": 87
}

Beispiel 4: Komplexe Logik mit 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

Eingabe:

{
  "contactEmail": "user@example.com"
}

Ausgabe:

{
  "contactEmail": "user@example.com",
  "isValidEmail": true
}

Beispiel 5: Primzahlprüfung

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

Eingabe:

{
  "testNumber": 97
}

Ausgabe:

{
  "testNumber": 97,
  "isPrime": true
}

Beispiel 6: Bedingte Logik

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

Eingabe:

{
  "creditScore": 65
}

Ausgabe:

{
  "creditScore": 65,
  "riskLevel": "MEDIUM"
}

Anwendungsfälle

• Mathematische Berechnungen: Komplexe Formeln, Finanzberechnungen, statistische Operationen
• String-Verarbeitung: Textformatierung, Validierung, Parsing, Verkettung
• Datums-/Zeitoperationen: Datumsarithmetik, Formatierung, Zeitzonenkonvertierungen
• Bedingte Logik: Geschäftsregeln, Datenvalidierung, Klassifizierung
• Datentransformation: Typkonvertierungen, Wertezuordnung, Normalisierung
• Benutzerdefinierte Algorithmen: Implementierung spezifischer Geschäftslogik, die sich mit Standard-Nodes nicht abbilden lässt

Hinweise

• Performance: Skripte werden einmal kompiliert und für nachfolgende Ausführungen zwischengespeichert
• Sicherheit: Skripte laufen in einer Sandbox-Umgebung mit eingeschränktem Zugriff
• Timeout: Geben Sie stets geeignete Timeout-Werte an, um Endlosschleifen zu vermeiden
• Speicher: Achten Sie bei komplexen Berechnungen auf den Speicherverbrauch
• Fehlerbehandlung: Verwenden Sie try-catch-Blöcke in Ihrem C#-Code für eine saubere Fehlerbehandlung
• Null-Sicherheit: Der Node behandelt Null-Werte automatisch gemäß der Direktive #nullable disable
• Typsicherheit: Alle Argumente sind stark typisiert und werden vor der Skriptausführung validiert