Embedded CSharp Scripts v2

Workflows can include custom C# Scripts that can optionally reference Nuget packages. Use Scripts where the Flowgear DSL (domain-specific language) is not able to appropriately express logic or mapping. The most common cases are:

  • incoming data does not have a schema that is known at design time, the Script applies logic based on naming conventions or other protocol-specific knowledge to convert the data into a staticically known shape so that it can be used by the DSL
  • an algorithm that isn't represented by a prebuilt Node. For example, you are interacting with an endpoint that requries a specialized way of encrypting or signing data
  • An endpoint for which Flowgear doesn't currently offer a specialized connector, the alternative would be REST or Web Request and that would require several Workflow steps to deal with authentication or some other implementation-specific concern

Add Script

Add the C# Script Node and start with one of its templates:

  • Basic scalar method for ordinary inputs and one result.
  • Object method for a typed object and several named Returns.
  • Large collection example for lazy IAsyncEnumerable<T> processing.

The Script.Content value is a complete C# source file. It must contain a namespace, exactly one public type decorated with the FgNode attribute, and exactly one Method decorated with the FgMethod.Invoke attribbute.

The compiler reads the Method signature and replaces the C# Step's dynamic Parameters and Returns with that contract. When you change a matching type, Flowgear retains compatible authored Values, Expressions, and Samples; fields that no longer exist are removed from the refreshed shape.

Minimal source shape

```csharp`
using Flowgear.Sdk;

namespace Flowgear.Scripts;

[FgNode("v2.NormalizeName", "Normalize Name", SupportedClusters.Anywhere)]
public sealed class NormalizeName
{
[FgMethod.Invoke(
NodeTypes.Processor,
"Execute",
"Normalizes a supplied name.",
"Result")]
public Task ExecuteAsync(
[FgParameter("Name", "The name to normalize.")] string name,
CancellationToken cancellationToken = default)
{
cancellationToken.ThrowIfCancellationRequested();
return Task.FromResult(name.Trim());
}
}


Flowgear supplies the `CancellationToken`; it does not appear as a Workflow Parameter. Use it in asynchronous or long-running work so `Stop` and execution deadlines can cancel the Method cooperatively.

The compiler automatically imports common System namespaces for collections, IO, LINQ, HTTP, threading, and tasks. Add `using Flowgear.Sdk;` and any other required namespaces to the source.

# Supported contracts

Use ordinary attributed Parameters and supported Task or asynchronous-enumerable Returns. Script-defined classes can expose Object and Array shapes, and `FgReturnContainer` with `FgReturn` can expose several top-level Returns.

# Preview, Debug, and publish

Preview compiles only the declaration shape, does not download NuGet packages, and never constructs or invokes the authored class. It can therefore validate the exposed contract without proving that package-dependent Method code compiles.

Debug and save/publish compilation use the complete source and exact package dependencies. Flowgear embeds the script into a Step-specific namespace in the compiled Workflow. Package runtime files are included in the published Workflow artifact when required.

At runtime, Flowgear constructs the embedded class for each Step invocation. Its values use ordinary mapping, logging, deferred-data, error, and cancellation behavior.

# Security and governance

An embedded script is executable code, not a sandboxed mapping Expression. Its source and NuGet dependencies execute inside the Runtime process. Someone who can change and publish the Workflow can change that code.

Review source, packages, network/file access, logging, and returned data before promotion. Pin every dependency to an exact version and repeat the review when the version changes. Prefer a purpose-built published Node when the capability needs reuse, Connection injection, dedicated lifecycle Methods, or central governance across many Workflows.

# Convert a Script to a Node

Script Node content is intended to make it easy to build a custom Node. See [Custom Nodes](/v2/features/custom-nodes) for more information.

# See also

See [Use NuGet Packages in a Script](/v2/guides/use-nuget-packages-in-a-script), [Compiled execution](/v2/concepts/compiled-execution), [Activation Modes and Timeouts](/v2/concepts/activation-modes-and-timeouts), and [Workflow Log Redaction](/v2/features/workflow-log-redaction).