C# (csharp)

Category: actions | Form: | Symbol: Cs

Execute compiled C#/.NET code in a sandboxed environment

Compiles and runs C#/.NET code in a sandboxed Firecracker VM. Code is compiled ahead of time and cached. Supports NuGet dependencies via spec.source.requirements. Put your code in spec.source.code or point to a git repository. Your code must define a Handler method.

Guide

Execute compiled C#/.NET code in a sandboxed Firecracker VM

What It Does

The C# element compiles and runs C#/.NET code inside an isolated Firecracker microVM. You supply source code (inline, from a file path, or from a git repository) and the platform restores NuGet dependencies, compiles the .NET project ahead of time, and caches the binary artifact. Subsequent invocations use the pre-compiled binary — there is no JIT warmup cost after the first deploy. Each run gets its own VM with guaranteed memory and CPU isolation.

Element Definition

Property	Value
Type	csharp
Category	functions
Form	atom
Symbol	Cs / #512BD4

Properties

Field	Type	Default	Description
source.type	string (enum)	inline	Source location: inline (code in spec), file (path in element workspace), or git (repository URL)
source.code	string	—	Inline C# source. Must define a public static handler method.
source.path	string	—	File path within the element workspace (for file type)
source.repository	string (URI)	—	Git repository URL (for git type)
source.ref	string	—	Git branch, tag, or commit SHA
source.requirements	array	[]	NuGet packages, e.g. ["Newtonsoft.Json@13.0", "Dapper@2.1"]
handler	string	Handler.Run	Entry point method. Must be public static.
dotnet_version	string (enum)	net8.0	Target framework moniker: net6.0, net8.0, or net9.0
memory_mb	integer	256	VM memory in MB (64–4096)
timeout_ms	integer	30000	Maximum execution time in milliseconds (100–900000)
environment	object	{}	Custom environment variables injected into the VM
layers	array	[]	Additional runtime layers
concurrency.reserved	integer	—	Reserved execution slots
concurrency.max	integer	—	Maximum concurrent executions
retry.max_attempts	integer	3	Retry attempts on failure
retry.backoff_ms	integer	1000	Initial retry backoff in milliseconds
retry.backoff_multiplier	number	2.0	Exponential backoff multiplier

Ports

Direction	Port	Type	Required	Description
Input	input	request	Yes	Arbitrary JSON payload passed to the handler as JsonElement
Output	output	request	Yes	Return value from the handler method
Output	error	event	No	Emitted when compilation or execution fails

Topology

• Lives in: actions/csharp/ repository
• Accepts modifiers: requirements, auth-policy, variable
• Uses resources: sql, document, vector, files

Capabilities

Capability	Description
sandboxed-execution	Runs in an isolated Firecracker microVM
compiled	Code is compiled ahead of time and the binary is cached for fast subsequent invocations
nuget-dependencies	NuGet package management for .NET dependencies
data-sources	Injected connections to sql, document, vector, and files elements
environment-injection	Custom environment variables available at runtime

Input Contract

Your handler receives the caller’s payload as a System.Text.Json.JsonElement. The platform automatically unwraps common envelope patterns (payload, data, input keys) and strips internal metadata, so your handler always sees the clean user data.

Direct invoke — the JSON body is passed through:

POST /api/{circle}/my-fn/ops/invoke
{"name": "Alice", "count": 3}

public static object Run(JsonElement input)
{
    // input contains {"name": "Alice", "count": 3}
    var name = input.TryGetProperty("name", out var n) ? n.GetString() : "World";
    return new { greeting = $"Hello, {name}!" };
}

Envelope invoke — the platform unwraps payload/data/input keys automatically:

POST /api/{circle}/my-fn/ops/invoke
{"payload": {"name": "Alice"}}

// handler still receives {"name": "Alice"} — envelope is stripped

Wired invoke (from automation steps or other elements) — the orchestrator shapes inputs based on port topology. Your handler receives the resolved payload, not raw wire data.

Quick Start

Creating via API

POST /api/{circle}/{project}/
Content-Type: application/json

{
  "element_type": "csharp",
  "slug": "greet",
  "name": "Greeter",
  "spec": {
    "handler": "Handler.Run",
    "source": {
      "type": "inline",
      "code": "using System.Text.Json;\npublic class Handler {\n  public static object Run(JsonElement input) {\n    var name = input.TryGetProperty(\"name\", out var n) ? n.GetString() : \"World\";\n    return new { message = $\"Hello, {name}!\" };\n  }\n}"
    }
  }
}

Invoking

POST /api/{circle}/{project}/greet/ops/invoke
Content-Type: application/json

{ "name": "Triform" }

Response:

{ "message": "Hello, Triform!" }

Deploying with NuGet Packages

Set NuGet packages in spec.source.requirements and deploy to compile and restore:

POST /api/{circle}/{project}/
Content-Type: application/json

{
  "element_type": "csharp",
  "slug": "http-fetcher",
  "spec": {
    "handler": "Handler.Run",
    "source": {
      "type": "inline",
      "requirements": ["Newtonsoft.Json@13.0"],
      "code": "using System.Text.Json;\nusing System.Net.Http;\nusing Newtonsoft.Json;\npublic class Handler {\n  private static readonly HttpClient Http = new();\n  public static async Task<object> Run(JsonElement input) {\n    var url = input.GetProperty(\"url\").GetString();\n    var body = await Http.GetStringAsync(url);\n    return new { body };\n  }\n}"
    }
  }
}

Then deploy:

POST /api/{circle}/{project}/http-fetcher/ops/deploy
Content-Type: application/json

{}

Writing Handlers

The handler must be a public static method on a class. It receives input as a System.Text.Json.JsonElement and returns any object that can be serialized to JSON. Async handlers returning Task<object> are supported.

using System.Text.Json;

public class Handler
{
    public static object Run(JsonElement input)
    {
        // Access properties using TryGetProperty for safe access
        var userId = input.TryGetProperty("user_id", out var uid)
            ? uid.GetString()
            : null;

        var threshold = input.TryGetProperty("threshold", out var t)
            ? t.GetInt32()
            : 100;

        // Perform computation
        var score = ComputeScore(userId);

        return new
        {
            user_id = userId,
            score = score,
            passed = score >= threshold
        };
    }

    private static int ComputeScore(string? userId) => 42;
}

Async Handlers

using System.Net.Http;
using System.Text.Json;

public class Handler
{
    private static readonly HttpClient Http = new();

    public static async Task<object> Run(JsonElement input)
    {
        var url = input.GetProperty("url").GetString();
        var response = await Http.GetStringAsync(url);
        return new { content = response };
    }
}

Accessing Environment Variables

Environment variables set in spec.environment (or injected by attached data elements) are available via Environment.GetEnvironmentVariable:

using System.Text.Json;

public class Handler
{
    public static object Run(JsonElement input)
    {
        var apiKey = Environment.GetEnvironmentVariable("MY_API_KEY");
        var baseUrl = Environment.GetEnvironmentVariable("SERVICE_URL");
        // Use apiKey and baseUrl...
        return new { ok = true };
    }
}

Using NuGet Packages

Declare packages in spec.source.requirements and add them to your .csproj or reference them via top-level using directives:

using System.Text.Json;
using Dapper;
using Microsoft.Data.Sqlite;

public class Handler
{
    public static async Task<object> Run(JsonElement input)
    {
        var connectionString = Environment.GetEnvironmentVariable("DB_CONNECTION");
        using var conn = new SqliteConnection(connectionString);
        var results = await conn.QueryAsync("SELECT * FROM items LIMIT 10");
        return new { items = results };
    }
}

NuGet package format: "PackageName@version", e.g. "Dapper@2.1" or "Newtonsoft.Json@13.0".

Project Patterns

C# is best suited for:

• Enterprise integrations — connecting to .NET-ecosystem services, Azure SDKs, Microsoft APIs
• Data processing — LINQ-based transformations, strong-typed pipelines
• Compiled performance — CPU-bound work that benefits from AOT compilation
• Type-safe contracts — strongly-typed input/output with compile-time validation

Example Project Spec

elements:
  - element_type: csharp
    slug: transform-order
    spec:
      handler: Handler.Run
      source:
        type: inline
        requirements: ["Newtonsoft.Json@13.0"]
        code: |
          using System.Text.Json;
          using Newtonsoft.Json.Linq;

          public class Handler
          {
              public static object Run(JsonElement input)
              {
                  var orderId = input.GetProperty("id").GetString();
                  var amount = input.GetProperty("amount").GetDecimal();
                  var currency = input.TryGetProperty("currency", out var c)
                      ? c.GetString()?.ToUpper()
                      : "USD";

                  return new
                  {
                      order_id = orderId,
                      total_cents = (int)(amount * 100),
                      currency,
                      processed_at = DateTimeOffset.UtcNow.ToString("o")
                  };
              }
          }

Applying Modifiers

Modifier	Use case
requirements	Require that specific variable or data resources are present before execution
auth-policy	Restrict who can invoke the function
variable	Inject environment-level configuration into the function

Common Mistakes

Using GetProperty instead of TryGetProperty for optional fields. GetProperty throws KeyNotFoundException if the property is absent. Use TryGetProperty for optional fields: input.TryGetProperty("key", out var val) ? val.GetString() : null.

Returning non-serializable types. The return value is serialized to JSON using System.Text.Json. Avoid returning types with circular references, Stream objects, or types without public properties. Use anonymous objects (new { ... }) or Dictionary<string, object> for dynamic shapes.

Forgetting to call deploy after changing requirements. NuGet packages are restored and compiled at deploy time, not at invocation time. After changing spec.source.requirements, call the deploy operation to rebuild before invoking.

Setting memory_mb below 256. The .NET runtime itself consumes approximately 100–200MB. Setting memory_mb below 256 typically causes OOM failures at startup. The platform will warn you but allow it.

Making the handler method non-static. The handler must be public static. Instance methods on a class require an instance, which the executor cannot create automatically. Use public static object Run(JsonElement input) or public static async Task<object> Run(JsonElement input).

Using dotnet_version: net6.0 for new functions. .NET 6 reached end-of-life in November 2024. Use net8.0 (LTS) or net9.0 for new functions.

Relationships

• Attaches to: auth-policy, variable, rate-limit, validation, alert
• Uses: sql, document, vector, files

Capabilities

• sandboxed-execution: Runs in an isolated Firecracker microVM
• compiled: Code is compiled ahead of time and the binary is cached for fast subsequent invocations
• nuget-dependencies: NuGet package management for .NET dependencies
• data-sources: Injected connections to sql, document, vector, and files elements
• environment-injection: Custom environment variables available at runtime

Properties

Property	Type	Default	Description
handler	string	—	Entry point method. Must be public static. Your C# code must define this method. Default: Handler.Run
source	object	—	Source code location. For inline code use type=“inline” with code in the “code” field. IMPORTANT: code goes in spec.source.code (NOT spec.code).
dotnet_version	string	"net8.0"	Target .NET framework moniker
memory_mb	integer	256	Memory allocation in MB
timeout_ms	integer	30000	Maximum execution time in milliseconds
environment	object	—	Custom environment variables injected at runtime
layers	array	[]	Additional runtime layers
concurrency	object	—	Controls how many copies can run simultaneously
retry	object	—	Automatic retry on failure

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attach

Post /ops/attach | Auth: Read

Attach this actor to a target element

Call this ON the modifier/resource element, passing target_id of the actor. The target’s contract.yaml must declare the modifier kind in attaches: or uses:. Priority controls evaluation order for modifiers (lower = first).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

deploy

Post /ops/deploy | Auth: Write

Compile source and restore NuGet packages for fast execution

Restore NuGet packages, compile the .NET project, and cache the build artifact. Promotes the element from ready to deployed state. No input required. Returns deploy_id, status, and compilation diagnostics. Must be in ready state. After deploy, invocations use the pre-compiled binary without recompiling.

detach

Post /ops/detach | Auth: Read

Detach this actor from a target element

diagnostics

Get /ops/diagnostics | Auth: Read

Check isolation service connectivity and health

Returns the status of the isolation executor that this element depends on for code execution. Use this to distinguish between user code errors and infrastructure issues when invoke returns 500. Returns isolation_reachable (bool), worker_available (bool), and last_error if any.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

get_attached_modifiers

Get /ops/attached | Auth: Read

Get elements that are attached to this action

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

invoke

Post /ops/invoke | Auth: Execute

Execute the C# handler with the provided input

Run the element’s C# handler method. Pass any JSON-serializable object as input. Returns the handler’s return value as output. Input contract: your handler receives the caller’s data as a System.Text.Json.JsonElement. The platform auto-unwraps envelope keys (payload, data, input) so you always get the clean payload. Execution runs in a Firecracker microVM with the configured memory_mb and timeout_ms limits. Code is compiled on first invocation and the binary is cached.

list_attachments

Get /ops/targets | Auth: Read

List all elements this action is attached to

Returns all target elements where this action is currently attached. Shows target_id, target_type, priority, and cascade_policy.

logs

Get /ops/logs | Auth: Read

Stream recent execution logs

Returns log lines from the most recent executions. Use since_run_id to fetch only logs after a specific run. Logs include stdout/stderr output from the .NET process.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

run_cancel

Post /ops/runs/{run_id}/cancel | Auth: Execute

Cancel a running execution

Only works on runs with status pending or running. Already-completed or failed runs cannot be cancelled. The run transitions to cancelled state and triggers run.cancelled event.

run_get

Get /ops/runs/{run_id} | Auth: Read

Get details of a specific run

Retrieve full details for a single run including input, output, logs, and resource usage. Pass run_id as a path parameter.

runs

Get /ops/runs | Auth: Read

List recent execution runs

Returns a paginated list of recent invocations ordered by started_at descending. Use limit and offset for pagination. Each run includes run_id, status, duration_ms, started_at, and a summary of input/output.

schema

Get /ops/schema | Auth: Read

Get input/output port schemas (MCP tools/list compatible)

Call this before invoking an actor to discover its expected input/output format. Returns MCP-compatible tool definitions — useful for building dynamic tool UIs or A2A integration.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

validate_source

Post /ops/validate_source | Auth: Write

Compile-check C# source code without deploying

Run the .NET compiler against the source and return diagnostics without producing a deployable artifact. Pass source object with code field. Returns valid (boolean), errors array with file/line/column/message/severity entries, and warnings array. Use this to catch compilation errors before deploy.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
CSHARP_COMPILATION_FAILED	validation	no	C# source code failed to compile
CSHARP_EXECUTION_FAILED	internal	no	C# code threw an unhandled exception during execution
CSHARP_TIMEOUT	timeout	yes	Execution exceeded the configured timeout_ms
CSHARP_HANDLER_NOT_FOUND	validation	no	The specified handler method was not found in the compiled assembly
CSHARP_NUGET_RESTORE_FAILED	validation	yes	One or more NuGet packages could not be restored
CSHARP_MEMORY_EXCEEDED	internal	no	Execution exceeded the configured memory_mb limit