Documentation

Architecture

How Aurora Workflows components fit together

High-Level Overview

Aurora Workflows has four layers that can be used independently or together:

Design-time - the Desktop Application lets you visually compose workflows saved as .awf (JSON) files.
Compile-time - the Compiler CLI bundles a .awf file with any referenced NuGet packages into a self-contained .awfc binary.
Runtime - the CLI Runner or any .NET host loads an .awfc bundle and executes the workflow task by task.
Hosting - the Hosting Engine stores published .awfc containers in SQL Server and schedules, executes, monitors and retries them across one or more nodes.

File Formats

Extension	Format	Description
`.awf`	JSON (UTF-8)	Human-readable workflow project produced and consumed by the Desktop Application. Can be version-controlled.
`.awfc`	Binary bundle	Compiled, self-contained workflow package. Contains the serialized task graph, package references, optionally embedded assemblies and (container version 1.1+) the designer data, so it can be opened and edited in the Desktop Application like an `.awf` file. Identified by the magic header `BWAURORAWF`.

Core Execution Model

A Workflow is a directed tree of tasks rooted at a StartTask. Each task follows a three-phase lifecycle:

DoSetupAsync() - called once when the workflow starts.
DoAsync(IWorkflowDataContext) - called each time the task is triggered.
DoTearDownAsync() - called when the workflow stops.

Tasks communicate exclusively through the Data Context - a typed key-value store. A task reads input from the context, performs work, and writes output back. Scope tasks (loops, conditionals, try/catch) create a child context that inherits from the parent.

Trigger Strategy

Workflows support two trigger strategies configured via WorkflowTriggerStrategy:

Sequential - triggers queue; the next execution begins only after the previous one completes.
Parallel - each trigger event starts an independent execution in its own context.

Expression Evaluation

Any task property that accepts an expression is evaluated by the Roslyn scripting engine (RoslynEvaluator) at runtime. Expressions are full C# snippets with access to the current IWorkflowDataContext as context.

=fileName.ToUpper()
Note: inside = expressions every visible workflow variable is a typed C# local (global ones also as _global_name). Inside task implementation code

Expressions are compiled once and cached per task instance. The evaluator resolves assemblies already loaded into the AppDomain by the ManagedWorkflow loader.

Assembly Loading

When an .awfc bundle is loaded by ManagedWorkflow, all embedded assemblies are extracted to a temporary directory and loaded into the current AppDomain via DotNetAssemblyLoaderProxyService. NuGet packages are resolved from a local package cache folder (default: .packages/ next to the executable).

Pause and Resume ⚠️ Experimental

This feature is highly experimental. Pause and Resume may not work correctly in all workflow configurations, particularly with complex scope tasks, parallel branches, or long-running async operations. Use with caution in production environments.

A running workflow can be paused by calling IWorkflow.PauseAsync(). The engine attempts to serialize the current task-tree state and the global variable space to a JSON snapshot string. Call IWorkflow.ResumeAsync(string json) with that snapshot to resume from the same point.