Shaunebu.Common.WorkflowManager 1.0.0

This is a .NET library for managing workflows and business processes in .NET MAUI or console applications. It provides a flexible engine to define, execute, monitor, and persist workflows.

🚀 Features

• Declarative Workflow Definitions: Define nodes, decisions, parallel branches, and transitions.

• Activities System: Encapsulate business logic in reusable workflow activities.

• Workflow Execution Engine: Start, resume, suspend, cancel workflows with real-time progress.

• Persistence & State Management: Save workflow state to memory, SQLite, or custom storage.

• Parallel & Conditional Flows: Support parallel branches, decision trees, and external event waits.

• Monitoring & Analytics: Track workflow progress, errors, and execution history.

• Integration with .NET MAUI: Display dynamic workflow dashboards and step views.

🧩 Advanced Workflow Features

• Compensation & Error Handling: Define compensating activities to revert workflow steps when failures occur.

• Timeouts & Wait Nodes: Pause execution until an external event occurs or a timeout expires.

• Parallel Branching & Joining: Execute multiple activities concurrently and synchronize on join nodes.

• Decision Trees: Support complex branching logic based on workflow context data.

🔄 Workflow Lifecycle

Workflows have a well-defined lifecycle:

1. Created – Workflow instance is initialized.

2. Running – Node execution in progress.

3. Suspended – Temporarily paused, can resume later.

4. Cancelled – Workflow execution stopped by user or system.

5. Completed – Successfully finished all nodes.

6. Failed – Execution failed and optionally triggered compensation.

🏗️ Architecture Overview

+-----------------------+
|  Workflow Definition  |
|  (Nodes + Transitions)|
+-----------+-----------+
            |
            v
+-----------------------+
|   Workflow Engine     |
|  Executes workflow    |
|  Handles transitions  |
+-----------+-----------+
            |
            v
+-----------------------+
|  Workflow Persistence |
|  Stores state & logs  |
+-----------------------+

🔑 Extensibility

• Custom Activities – Implement WorkflowActivity for domain-specific logic.

• Custom Persistence – Implement IWorkflowPersistence for databases like SQLite, PostgreSQL, or cloud storage.

• Custom Serialization – Override workflow serialization with JSON, XML, or protobuf.

📊 Monitoring & Analytics

• Track active workflow instances.

• Monitor progress per node and phase.

• Retrieve execution history with timestamps and errors.

• Identify bottlenecks in parallel or decision-heavy workflows.

🎛️ Integration Points

• Dependency Injection: Register engine, activities, and persistence in .NET MAUI or ASP.NET Core.

• UI Integration: Bind workflow instance data to dashboards, progress bars, and step views.

• Event-Driven: Subscribe to workflow events (node started, completed, failed) for notifications or logging.

💡 Best Practices

• Keep activities small and focused.

• Use decision nodes instead of deeply nested conditions.

• Persist state frequently for resiliency in long-running workflows.

• Reuse activities across workflows for maintainability.

🧪 Testing & Debugging

• Unit Test Activities independently from the engine.

• Simulate workflows with in-memory persistence for integration tests.

• Use DependencyGraphDot() to visualize workflow structure during debugging.

📦 Installation

Install via NuGet:

dotnet add package Shaunebu.Common.WorkflowManager

🏗️ Core Concepts

Workflow Definition

A workflow consists of nodes and transitions:

• Start Node: Entry point of the workflow.

• Activity Node: Executes a business logic unit.

• Decision Node: Conditional branching.

• Parallel Node: Executes branches in parallel.

• End Node: Marks workflow completion.

Example WorkflowNode:

public abstract class WorkflowNode
{
    public string Id { get; set; }
    public string Name { get; set; }
    public NodeType Type { get; set; }
    public abstract Task<NodeResult> ExecuteAsync(WorkflowContext context);
}

Workflow Context

Stores runtime data and workflow status:

public class WorkflowContext
{
    public string InstanceId { get; }
    public string CurrentNodeId { get; }
    public WorkflowStatus Status { get; }
    public void SetData<T>(string key, T value);
    public T GetData<T>(string key);
}

Workflow Activity

Encapsulates business logic:

public class ValidateOrderActivity : WorkflowActivity
{
    public override async Task<ActivityResult> ExecuteAsync(WorkflowContext context)
    {
        var order = context.GetData<Order>("Order");
        // Validate order logic
        return ActivityResult.Success();
    }
}

⚙️ Engine API

public class WorkflowEngine
{
    public WorkflowEngine(IWorkflowPersistence persistence, ILogger? logger = null);

    public Task<WorkflowExecutionResult> StartAsync(WorkflowDefinition definition, object inputData, CancellationToken token);
    public Task<WorkflowExecutionResult> ResumeAsync(string instanceId, CancellationToken token);
    public Task<IEnumerable<WorkflowInstance>> GetActiveInstancesAsync();
    public Task<WorkflowInstance> GetInstanceAsync(string instanceId);
    public event EventHandler<WorkflowEvent> WorkflowEvent;
}

💡 Usage Example

using Shaunebu.Common.WorkflowManager.Builder;
using Shaunebu.Common.WorkflowManager.Engine;
using Shaunebu.Common.WorkflowManager.Client.Activities;
using Shaunebu.Common.WorkflowManager.Persistence;

// Setup persistence and engine
var persistence = new InMemoryWorkflowPersistence();
var engine = new WorkflowEngine(persistence, logger: null);

// Build workflow definition
var workflow = new WorkflowDefinitionBuilder("OrderProcessing")
    .WithVersion("1.0")
    .AddStart("start")
    .AddActivity("validateOrder", typeof(ValidateOrderActivity))
    .AddDecision("paymentCheck")
    .AddActivity("processPayment", typeof(ProcessPaymentActivity))
    .AddActivity("generateInvoice", typeof(GenerateInvoiceActivity))
    .AddActivity("notifyFailure", typeof(NotifyFailureActivity))
    .AddEnd("end")
    .AddTransition("start", "validateOrder")
    .AddTransition("validateOrder", "paymentCheck")
    .AddTransition("paymentCheck", "processPayment", async ctx => await Task.FromResult(ctx.Get<bool>("orderValid")))
    .AddTransition("paymentCheck", "notifyFailure", async ctx => await Task.FromResult(!ctx.Get<bool>("orderValid")))
    .AddTransition("processPayment", "generateInvoice")
    .AddTransition("generateInvoice", "end")
    .AddTransition("notifyFailure", "end")
    .Build();

// Start workflow
var result = await engine.StartAsync(workflow, new { OrderId = 1234 }, CancellationToken.None);
Console.WriteLine($"Workflow success: {result.IsSuccess}");

📊 Visualization

Generate DOT graph for your workflow:

public string DependencyGraphDot(WorkflowDefinition def)
{
    var sb = new StringBuilder();
    sb.AppendLine("digraph Workflow {");

    foreach (var kvp in def.Nodes)
    {
        var nodeId = kvp.Key;
        var transitions = def.Transitions.Where(tr => tr.FromNodeId == nodeId);
        foreach (var tr in transitions)
        {
            sb.AppendLine($"\"{tr.FromNodeId}\" -> \"{tr.ToNodeId}\";");
        }
    }

    sb.AppendLine("}");
    return sb.ToString();
}

🛠️ Persistence

Interface to implement custom persistence:

public interface IWorkflowPersistence
{
    Task SaveInstanceAsync(WorkflowInstance instance);
    Task<WorkflowInstance> LoadInstanceAsync(string instanceId);
    Task DeleteInstanceAsync(string instanceId);
    Task<IEnumerable<WorkflowInstance>> FindInstancesAsync(WorkflowQuery query);
}

🎯 Use Cases

• Order Processing & Checkout: Sequential validation, payment, invoice generation.

• User Onboarding: Multiple screens, decision logic, permission requests.

• Document Approval: Parallel reviewer branches, approval/rejection logic.

• Business Processes: Complex workflows with events, compensation, and retries.

✅ Benefits

• Flexibility: Modify workflows without changing code.

• Visibility: Track progress and errors in real-time.

• Reusability: Encapsulate business logic in activities.

• Resilience: Retry, compensation, and error handling.

• Scalability: Parallel branches, complex conditional flows.

📚 References

• Inspired by BPMN and workflow engines like Elsa Workflows

• Compatible with .NET MAUI, .NET 8, and console apps