WorkflowForge logo

WorkflowForge Documentation

Build .NET workflows with clear guidance, focused examples, and a zero-dependency core.

Build and Test NuGet NuGet Downloads License Quality Gate Status Coverage Reliability Rating Security Rating Maintainability Rating Ko-fi

Get started API reference .NET API

Core Concepts

Understand foundries, smiths, operations, and lifecycle events.

Performance First

Benchmark-backed results with microsecond execution and minimal memory.

Extensions Ready

Logging, resilience, persistence, and observability without conflicts.

What is WorkflowForge?

WorkflowForge is a zero-dependency workflow orchestration framework for .NET. Twelve BenchmarkDotNet scenarios against Workflow Core and Elsa (same scripted logic) show microsecond-level medians and small heaps on our harness. Forge, foundry, and smith name the pieces so composition and tests read the same everywhere.

Key Features

  • 2-583x faster than those libraries on the scenarios we measured (runtime and scenario matter).
  • About 1-533x less memory in the same runs, case by case.
  • Zero package dependencies on the core assembly; extensions are optional NuGet add-ons.
  • Compensation hooks on every operation (saga-style rollback when you implement RestoreAsync).
  • Thirteen packages total: one core, eleven extensions, plus WorkflowForge.Testing. Resilience.Polly and Logging.Serilog isolate their third-party library with ILRepack.
  • Fluent builders, the industrial metaphor, and 37 samples that ramp from hello world to persistence and recovery.

The Industrial Metaphor

WorkflowForge names pieces with a simple industrial metaphor:

  • The Forge (WorkflowForge static class) is the entry point for building workflows.
  • Foundries (IWorkflowFoundry) hold mutable state and services while operations run.
  • Smiths (IWorkflowSmith) drive execution order, compensation, and lifecycle events.
  • Operations (IWorkflowOperation) are the individual units of work in the graph.

Read it literally: data (raw material) moves through operations (tools) inside a foundry (workspace), while the smith (orchestrator) runs the sequence.

Quick Start

dotnet add package WorkflowForge

using WorkflowForge;

var workflow = WorkflowForge.CreateWorkflow("HelloWorld")
    .AddOperation("SayHello", async (foundry, ct) => {
        foundry.Logger.LogInformation("Hello, WorkflowForge!");
    })
    .Build();

using var smith = WorkflowForge.CreateSmith();
await smith.ForgeAsync(workflow);

Core Abstractions

IWorkflow

Complete workflow definition with operations and metadata.

public interface IWorkflow : IDisposable
{
    Guid Id { get; }
    string Name { get; }
    string? Description { get; }
    string Version { get; }
    IReadOnlyList<IWorkflowOperation> Operations { get; }
}

IWorkflowFoundry

Execution environment providing context, logging, and services.

public interface IWorkflowFoundry :
    IWorkflowExecutionContext,
    IWorkflowMiddlewarePipeline,
    IOperationLifecycleEvents,
    IDisposable
{
    Guid ExecutionId { get; }
    IWorkflow? CurrentWorkflow { get; }
    ConcurrentDictionary<string, object?> Properties { get; }
    IFoundryServices Services { get; }
    IWorkflowForgeLogger Logger { get; }
    WorkflowForgeOptions Options { get; }
    IServiceProvider? ServiceProvider { get; }
    bool IsFrozen { get; }
}

Properties holds workflow data and is never auto-disposed. Services holds extension-owned objects and is disposed when the foundry lease ends - see Foundry lease and resource lifetime.

IWorkflowSmith

Orchestration engine executing workflows.

public interface IWorkflowSmith : IDisposable, IWorkflowLifecycleEvents, ICompensationLifecycleEvents
{
    Task ForgeAsync(IWorkflow workflow, CancellationToken cancellationToken = default);
    Task ForgeAsync(IWorkflow workflow, ConcurrentDictionary<string, object?> data, CancellationToken cancellationToken = default);
    Task ForgeAsync(IWorkflow workflow, IWorkflowFoundry foundry, CancellationToken cancellationToken = default);
}

IWorkflowOperation

Individual executable operation within a workflow.

public interface IWorkflowOperation : IDisposable
{
    Guid Id { get; }
    string Name { get; }
    
    Task<object?> ForgeAsync(object? inputData, IWorkflowFoundry foundry, CancellationToken cancellationToken = default);
    Task RestoreAsync(object? outputData, IWorkflowFoundry foundry, CancellationToken cancellationToken = default);
}

Override RestoreAsync when you need compensation behavior. Compensation calls RestoreAsync on every completed operation; the base class default is a no-op, so operations that do not override it simply do nothing.

Extensions Ecosystem

WorkflowForge provides 13 packages (1 core + 11 extensions + 1 testing utility):

Package Purpose
Testing Unit testing utilities with FakeWorkflowFoundry
DependencyInjection Microsoft.Extensions.DependencyInjection integration
Serilog Logging Structured logging integration
Resilience Core retry abstractions
Polly Resilience Circuit breakers, retries, timeout policies
Validation Input validation with DataAnnotations
Audit Logging Compliance & audit trails
Persistence Workflow state storage
Persistence Recovery Resume interrupted workflows
Performance Monitoring Metrics & profiling
Health Checks Application health monitoring
OpenTelemetry Distributed tracing

Dependency Isolation: The two extensions that bundle a third-party library — Resilience.Polly and Logging.Serilog — internalize it with ILRepack. Microsoft/System packages stay external and resolve normally.

Performance Highlights

Based on BenchmarkDotNet testing (12 scenarios, 10 iterations per job) against Workflow Core and Elsa Workflows:

583x
Faster (State Machine)
533x
Less Memory
17.9μs
Min Execution
3.4KB
Min Memory

Benchmark Comparison

Runtime Scenario vs WorkflowCore vs Elsa Memory Advantage
.NET 10.0 State Machine 288x faster 583x faster 44-250x less
.NET 8.0 State Machine 231x faster 555x faster 45-252x less
.NET FX 4.8 State Machine 271x faster N/A† 53x less
.NET 10.0 Concurrent (8 wf) 183x faster 382x faster 20-123x less
.NET 8.0 Concurrent (8 wf) 138x faster 387x faster 20-124x less
.NET FX 4.8 Concurrent (8 wf) 267x faster N/A† 14x less

† Elsa does not support .NET Framework 4.8. See Competitive Analysis for all 12 scenarios.

State Machine Execution (25 Transitions)
State machine scenario, .NET 10.0 median (see competitive analysis for caveats)
59.3μs
17.1ms
34.6ms
.NET 10.0
59.7μs
13.8ms
33.2ms
.NET 8.0
55.9μs
15.2ms
.NET FX 4.8
WorkflowForge
Workflow Core
Elsa Workflows

Test System: Windows 11 (25H2), .NET 8.0.24 / .NET 10.0.3 / .NET FX 4.8.1, BenchmarkDotNet v0.15.8, 10 iterations per job

Support & Community