Aurora.Workflows.Fluent 0.3.1.7

Aurora Workflows - Fluent API

A modern, intuitive fluent API for building workflows in C#. Create complex automation workflows with a clean, readable syntax.

Features

• Fluent Interface: Chain method calls for readable workflow definitions
• Type-Safe: Strong typing with IntelliSense support
• Lambda Configuration: Configure tasks inline with lambda expressions
• Extension Methods: Rich set of extensions for common patterns
• Async/Await: Full async support throughout the API
• Flexible Scoping: Control variable scope at task level

Installation

dotnet add package Aurora.Workflows.Fluent

Quick Start

Basic Sequential Workflow

using Aurora.Workflows.Fluent;
using Aurora.Workflows.Tasks;
using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());

var workflow = FluentWorkflow
    .Create("Simple File Processing", loggerFactory)
    .AddTask<ReadFileTask>(t => t.Expression = "\"input.txt\"")
        .SetOutputVariable("fileData")
    .AddChildTask<WriteFileTask>(t => t.Expression = "\"output.txt\"")
        .SetInputVariable("fileData")
    .Build();

// Execute the workflow
await workflow.StartAsync();

Workflow with Conditions

var workflow = FluentWorkflow
    .Create("Conditional Processing", loggerFactory)
    .AddTask<SetVariableTask>(t => 
    {
        t.Expression = "DateTime.Now.Hour";
        t.CustomOutputVariableName = "currentHour";
    })
    .Decide(
        expression: "context.Get<int>(\"currentHour\") < 12",
        name: "Check Time of Day",
        whenTrue: b => b
            .Print("Good morning!", ConsoleColor.Green)
            .AddChildTask<MorningTask>(),
        whenFalse: b => b
            .Print("Good afternoon!", ConsoleColor.Blue)
            .AddChildTask<AfternoonTask>()
    )
    .Build();

await workflow.ExecuteAsync();

Parallel Execution

var workflow = FluentWorkflow
    .Create("Parallel Processing")
    .AddTask<StartTask>()
        .Parallel(
            new ProcessTask1 { Name = "Process A" },
            new ProcessTask2 { Name = "Process B" },
            new ProcessTask3 { Name = "Process C" }
        )
    .Build();

await workflow.ExecuteAsync();

Error Handling and Retry

var workflow = FluentWorkflow
    .Create("Resilient Workflow")
    .AddTask<UnreliableTask>()
        .WithErrorHandling(
            continueOnError: true,
            retryCount: 3,
            retryInterval: TimeSpan.FromSeconds(5)
        )
    .AddChildTask<FallbackTask>()
        .IgnoreErrors()
    .Build();

Using Extension Methods

var workflow = FluentWorkflow
    .Create("Advanced Workflow")
    .AddTask<StartTask>()
        // Chain multiple tasks
        .Chain(
            new Task1(),
            new Task2(),
            new Task3()
        )
        // Add conditional task
        .AddTaskIf<DebugTask>(
            condition: Environment.GetEnvironmentVariable("DEBUG") == "true",
            configure: t => t.Message = "Debug mode active"
        )
        // Repeat a task multiple times
        .Repeat<ProcessItemTask>(5, (task, index) =>
        {
            task.Name = $"Process Item {index}";
            task.ItemIndex = index;
        })
        // Group related tasks
        .Group("Data Processing", builder => builder
            .AddChildTask<LoadDataTask>()
            .AddChildTask<TransformDataTask>()
            .AddChildTask<SaveDataTask>()
        )
    .Build();

Variable Scoping

var workflow = FluentWorkflow
    .Create("Scoped Variables")
    .AddTask<ReadFileTask>()
        .WithVariables(output: "fileContent")
        .UseGlobalScopeForOutput()  // Available globally
    .AddChildTask<ProcessTask>()
        .WithVariables(input: "fileContent", output: "result")
        .UseParentScopeForInput()   // Read from parent
    .AddChildTask<WriteTask>()
        .WithVariables(input: "result")
        .UseGlobalScopeForInput()   // Read from global
    .Build();

Triggers

var workflow = FluentWorkflow
    .Create("Scheduled Workflow")
    
    // Add cron trigger (daily at 2 AM)
    .TriggerOnSchedule("0 2 * * *", "Daily Backup")
    
    // Add file watcher
    .TriggerOnFileChange(@"C:\Uploads", "*.xml")
    
    // Add periodic trigger
    .TriggerPeriodic(TimeSpan.FromHours(1))
    
    .AddTask<BackupTask>()
    .Build();

// Start the workflow (will run based on triggers)
await workflow.StartAsync();

// Keep running until stopped
// await workflow.StopAsync();

Custom Task Configuration

var workflow = FluentWorkflow
    .Create("Custom Configuration")
    .AddTask<MyCustomTask>(task =>
    {
        task.Parameter1 = "value";
        task.Parameter2 = 42;
    })
        .WithName("My Special Task")
        .SetOutputVariable("result")
        .WithDelay(
            preDelay: TimeSpan.FromSeconds(1),
            postDelay: TimeSpan.FromSeconds(2)
        )
        .BreakOnDebug(beforeExecution: true)
    .Build();

ForEach Pattern

var files = new[] { "file1.txt", "file2.txt", "file3.txt" };

var workflow = FluentWorkflow
    .Create("Batch Processing")
    .AddTask<StartTask>()
        .ForEach<ProcessFileTask, string>(files, (task, file) =>
        {
            task.FileName = file;
            task.Name = $"Process {file}";
        })
    .Build();

Workflow State Management

var workflow = FluentWorkflow
    .Create("Long Running Workflow")
    .AddTask<Task1>()
    .AddChildTask<Task2>()
    .Build();

// Start workflow
await workflow.StartAsync();

// Pause and save state
var state = await workflow.PauseAsync();
File.WriteAllText("workflow-state.json", state);

// Later, resume from saved state
var savedState = File.ReadAllText("workflow-state.json");
await workflow.ResumeAsync(savedState);

Debugging Support

var workflow = FluentWorkflow
    .Create("Debug Workflow")
    .AddTask<DataTask>()
        .SetOutputVariable("data")
        .Debug("Data loaded successfully", ConsoleColor.Green)
    .AddChildTask<ProcessTask>()
        .SetInputVariable("data")
        .BreakOnDebug(beforeExecution: true)  // Debugger breaks here
        .PrintExpression("context.Get<string>(\"data\")")
    .Build();

Advanced Examples

Complete Data Processing Pipeline

var workflow = FluentWorkflow
    .Create("ETL Pipeline", loggerFactory)
    
    // Configure workflow
    .WithName("Daily ETL")
    .WithTags("ETL", "Data", "Production")
    .TriggerOnSchedule("0 2 * * *")  // 2 AM daily
    
    // Extract phase
    .AddTask<ExecuteSqlQueryTask>(t =>
    {
        t.ConnectionString = "\"Server=...\"";
        t.Expression = "\"SELECT * FROM Orders WHERE Date = GETDATE()\"";
    })
        .WithName("Extract Orders")
        .SetOutputVariable("orders")
        .Retry(TimeSpan.FromSeconds(10), maxRetries: 3)
    
    // Transform phase (parallel processing)
    .Async("Transform Data")
        .Parallel(
            new ValidateDataTask { Name = "Validate" },
            new EnrichDataTask { Name = "Enrich" },
            new FilterDataTask { Name = "Filter" }
        )
        .SetInputVariable("orders")
        .SetOutputVariable("transformedData")
    
    // Load phase
    .AddChildTask<WriteToDataWarehouseTask>()
        .WithName("Load to DW")
        .SetInputVariable("transformedData")
        .WithErrorHandling(continueOnError: false, retryCount: 5)
    
    // Notification
    .AddChildTask<SendEmailTask>(t =>
    {
        t.To = "admin@company.com";
        t.Subject = "ETL Completed";
    })
        .IgnoreErrors()  // Don't fail workflow if email fails
    
    .Build();

await workflow.StartAsync();

Dynamic Workflow Construction

var workflow = FluentWorkflow.Create("Dynamic Workflow");

// Conditionally add tasks based on configuration
if (config.EnableLogging)
{
    workflow = workflow.AddTask<LogTask>();
}

// Add tasks based on data
foreach (var source in dataSources)
{
    workflow.AddTask<DataSourceTask>(t => t.Source = source);
}

var built = workflow.Build();

API Reference

FluentWorkflow

• Create(string name, ILoggerFactory logger = null) - Creates a new workflow builder
• Load(string json, ILoggerFactory logger = null) - Loads workflow from JSON

FluentWorkflowBuilder

Task Management:

• AddTask(IWorkflowTaskBase task) - Adds root task
• AddTask<TTask>(Action<TTask> configure) - Adds and configures root task
• RemoveTask(IWorkflowTaskBase task) - Removes a task

Triggers:

• TriggerOnce() - Execute immediately
• TriggerPeriodic(TimeSpan interval) - Execute periodically
• TriggerOnSchedule(string cron) - Execute on schedule
• TriggerOnFileChange(string path, string filter) - Execute on file changes
• AddTrigger<TTrigger>(Action<TTrigger> configure) - Add custom trigger

Configuration:

• WithName(string name) - Set workflow name
• WithTags(params string[] tags) - Add tags
• ConfigureWorkflow(Action<IWorkflow> configure) - Configure workflow

Execution:

• Build() - Build workflow
• Execute(IWorkflowDataContext context) - Execute synchronously
• ExecuteAsync(IWorkflowDataContext context) - Execute asynchronously
• StartAsync() - Start long-running workflow
• StopAsync() - Stop workflow
• PauseAsync() - Pause and save state
• ResumeAsync(string state) - Resume from state

FluentWorkflowTaskBuilder

Task Addition:

• AddChildTask(IWorkflowTaskBase task) - Add sequential task
• AddBranchTask(IWorkflowTaskBase task) - Add parallel task
• AddTask<TTask>(Action<TTask> configure) - Add and configure task
• AddAsyncChildTask(IWorkflowTaskBase task) - Add async task

Built-in Tasks:

• Wait(TimeSpan duration) - Add wait task
• Decide(string expression, ...) - Add conditional task
• Print(string text, ConsoleColor? color) - Add debug output
• PrintExpression(string expr, ConsoleColor? color) - Print expression result
• SetVariable(string name, string expression) - Set variable
• Async(string name, bool useThreadPool) - Async execution

Configuration:

• SetInputVariable(string name) - Configure input variable
• SetOutputVariable(string name) - Configure output variable
• WithName(string name) - Set task name
• WithVariables(string input, string output) - Configure both variables
• WithScoping(bool useGlobal, bool inputFromParent, bool outputToParent) - Configure scoping

Error Handling:

• IgnoreErrors() - Continue on error
• Retry(TimeSpan interval, int maxRetries) - Enable retry
• WithErrorHandling(bool continue, int retries, TimeSpan interval) - Complete error config

Timing:

• WithDelay(TimeSpan? pre, TimeSpan? post) - Add delays

Debugging:

• BreakOnDebug(bool before, bool after) - Break when debugging
• SkipOnDebug() - Skip when debugger attached
• Debug(string message, ConsoleColor? color) - Add debug output

Control Flow:

• Configure<TTask>(Action<TTask> action) - Inline configuration
• Commit() - Return to workflow builder
• Build() - Build workflow

Extension Methods (FluentWorkflowExtensions)

• Chain(params IWorkflowTaskBase[] tasks) - Chain tasks sequentially
• Parallel(params IWorkflowTaskBase[] tasks) - Execute tasks in parallel
• Repeat<TTask>(int count, Action<TTask, int> configure) - Repeat task
• ForEach<TTask, TItem>(IEnumerable<TItem> items, Action<TTask, TItem> configure) - Iterate collection
• Group(string name, Action<FluentWorkflowTaskBuilder> configure) - Group tasks
• Apply(Action<FluentWorkflowTaskBuilder> configure) - Apply configuration
• When(bool condition, Action<FluentWorkflowTaskBuilder> configure) - Conditional config
• AddTaskIf<TTask>(bool condition, Action<TTask> configure) - Conditional task
• Run() - Execute workflow synchronously
• RunAsync() - Execute workflow asynchronously

Best Practices

1. Use Type-Safe Configuration: Leverage generic methods and lambda expressions
2. Name Your Tasks: Use WithName() for better debugging and monitoring
3. Handle Errors Appropriately: Use WithErrorHandling() for critical operations
4. Use Variable Scoping: Be explicit about variable scope for clarity
5. Leverage Extension Methods: Use Chain, Parallel, ForEach for cleaner code
6. Add Debug Output: Use Debug() and Print() during development
7. Configure Retry Logic: Add retry for network/external operations
8. Group Related Tasks: Use Group() to organize complex workflows

Migration from Old API

Old API:

var workflow = FluentWorkflow.Create("My Workflow");
var builder = workflow.SetupTasks();
builder.AddChildTask(new MyTask());
builder.SetOutputVariable("result");
var wf = builder.Commit().Get();

New API:

var workflow = FluentWorkflow
    .Create("My Workflow")
    .AddTask<MyTask>()
        .SetOutputVariable("result")
    .Build();

License

Copyright © Ben Wagner 2020+

See LICENCE.MD for details.