WorkflowForge Documentation

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

Get started API reference

What is WorkflowForge?

WorkflowForge is a zero-dependency workflow orchestration framework for .NET with microsecond-level performance and minimal memory footprint. It provides a clean, industrial metaphor for building workflows that are fast, maintainable, and production-ready.

Key Features

• High Performance: 11-540x faster than alternatives in benchmarks
• Minimal Memory: 9-573x less memory usage
• Zero Dependencies: Core package with no external dependencies
• Production Ready: Built-in compensation (saga pattern), comprehensive testing
• Extension Ecosystem: 13 packages (11 extensions + Testing) with zero version conflicts
• Developer Experience: Fluent API, clear metaphor, 33 progressive samples

The Industrial Metaphor

WorkflowForge uses an industrial metaphor that makes workflows intuitive:

• The Forge (WorkflowForge static class) - Main factory for creating workflows
• Foundries (IWorkflowFoundry) - Execution environments where operations run
• Smiths (IWorkflowSmith) - Orchestration engines managing workflow execution
• Operations (IWorkflowOperation) - Individual tasks within workflows

This metaphor provides clarity: data (raw materials) flows through operations (tools) in a foundry (workspace), orchestrated by a smith (craftsman).

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; }
    bool SupportsRestore { 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; }
    bool SupportsRestore { get; }
    
    Task<object?> ForgeAsync(object? inputData, IWorkflowFoundry foundry, CancellationToken cancellationToken = default);
    Task RestoreAsync(object? outputData, IWorkflowFoundry foundry, CancellationToken cancellationToken = default);
}

Extensions Ecosystem

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

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:

Benchmark Comparison

Test System: Windows 11 (25H2), .NET 8.0.23, BenchmarkDotNet v0.15.8, 50 iterations

Support & Community

• GitHub Repository: animatlabs/workflow-forge
• Issues: GitHub Issues
• License: MIT License
• Contributing: Contributing Guidelines