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

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

  • 13x–511x faster than those libraries on the scenarios we measured (runtime and scenario matter).
  • About 6x–575x 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, with ILRepack isolating third-party bits.
  • Fluent builders, the industrial metaphor, and 33 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; }
    IWorkflowForgeLogger Logger { get; }
    WorkflowForgeOptions Options { get; }
    IServiceProvider? ServiceProvider { get; }
}

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. The base class default is a no-op, and WorkflowForge skips those operations during compensation.

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: Extensions internalize dependencies with ILRepack while keeping Microsoft/System packages external.

Performance Highlights

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

511x
Faster (State Machine)
575x
Less Memory
8.75μs
Min Execution
3.4KB
Min Memory

Benchmark Comparison

Runtime Scenario vs WorkflowCore vs Elsa Memory Advantage
.NET 10.0 State Machine 455x faster 511x faster 46-249x less
.NET 8.0 State Machine 305x faster 485x faster 46-248x less
.NET FX 4.8 State Machine 303x faster N/A† 57x less
.NET 10.0 Concurrent (8 wf) 139x faster 251x faster 22-134x less
.NET 8.0 Concurrent (8 wf) 118x faster 288x faster 23-134x less
.NET FX 4.8 Concurrent (8 wf) 251x faster N/A† 15x 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)
65μs
29.5ms
33.1ms
.NET 10.0
71μs
21.7ms
34.4ms
.NET 8.0
61μs
18.5ms
.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, 50 iterations

Support & Community