DEV Community: Mohammad Anzawi

Orchestrix.Mediator: A Modern Mediator Engine for .NET 8/9/10+

Mohammad Anzawi — Sun, 20 Jul 2025 21:48:02 +0000

Tired of hitting limits with MediatR?

Meet Orchestrix.Mediator — a next-gen mediator engine designed for the modern .NET ecosystem.

✨ Why Orchestrix.Mediator?

Orchestrix.Mediator isn’t just a clone of MediatR. It’s a reimagined mediator with first-class support for the features developers now expect:

✅ Zero-reflection dispatch via source generators

✅ Parallel notifications with built-in fan-out

✅ Asynchronous streaming using IAsyncEnumerable<T>

✅ Hook-based diagnostics for tracing, logging, and metrics

✅ CQRS extensions with ICommand, IQuery, and semantic handlers

✅ Minimal API & Controller support

✅ Fully ValueTask-based and AOT-safe

All while preserving the simplicity and ergonomics of MediatR.

⚙️ Quick Start

1. Install

dotnet add package Orchestrix.Mediator

Optional extensions:

dotnet add package Orchestrix.Mediator.SourceGenerators
dotnet add package Orchestrix.Mediator.Cqrs

2. Register in `Program.cs`

builder.Services.AddOrchestrix(cfg => 
{
    cfg.UseSourceGenerator() // optional: enables zero-reflection dispatch
       .RegisterHandlersFromAssemblies(typeof(MyHandler).Assembly);
});

3. Define a Command + Handler

public record CreateUserCommand(string Name) : IRequest<Guid>;

public class CreateUserHandler : IRequestHandler<CreateUserCommand, Guid>
{
    public ValueTask<Guid> Handle(CreateUserCommand request, CancellationToken ct)
    {
        return ValueTask.FromResult(Guid.NewGuid());
    }
}

4. Dispatch via `ISender`

var id = await sender.Send(new CreateUserCommand("Mohammad"));

📢 Notifications with Fan-Out

public record UserRegistered(string Email) : INotification;

public class LogHandler : INotificationHandler<UserRegistered>
{
    public ValueTask Handle(UserRegistered n, CancellationToken ct)
        => ValueTask.CompletedTask;
}

public class EmailHandler : IParallelNotificationHandler<UserRegistered>
{
    public async ValueTask Handle(UserRegistered n, CancellationToken ct)
    {
        await Task.Delay(100);
        Console.WriteLine($"Welcome {n.Email}");
    }
}

📣 Both handlers will run: one sequentially, the other in parallel!

await publisher.Publish(new UserRegistered("user@example.com"));

📡 Streaming with `IAsyncEnumerable<T>`

public record GetUsers(int Count) : IStreamRequest<UserDto>;

public class GetUsersHandler : IStreamRequestHandler<GetUsers, UserDto>
{
    public async IAsyncEnumerable<UserDto> Handle(GetUsers req, [EnumeratorCancellation] CancellationToken ct)
    {
        for (int i = 0; i < req.Count; i++)
        {
            yield return new UserDto(Guid.NewGuid(), $"User-{i + 1}");
            await Task.Delay(100, ct);
        }
    }
}

Dispatch:

await foreach (var user in sender.CreateStream(new GetUsers(5), ct))
{
    Console.WriteLine(user.Name);
}

🪝 Built-in Hooks for Tracing & Logging

Orchestrix.Mediator supports lifecycle instrumentation via hooks:

ISendHook
IPublishHook
IStreamHook

Example:

public class LoggingHook : ISendHook
{
    public ValueTask OnSendStart(object request, CancellationToken ct)
        => Log($"[SEND] Start: {request.GetType().Name}");

    public ValueTask OnSendComplete(object request, object? response, CancellationToken ct)
        => Log($"[SEND ✅] Completed: {response}");

    public ValueTask OnSendError(object request, Exception ex, CancellationToken ct)
        => Log($"[SEND ❌] Failed: {ex.Message}");
}

services.AddOrchestrix(cfg => cfg.AddHook<LoggingHook>());

🧱 Pipelines Still Here

Need validation, logging, or retry logic?

public class LoggingBehavior<TReq, TRes> : IPipelineBehavior<TReq, TRes>
    where TReq : IRequest<TRes>
{
    public async ValueTask<TRes> Handle(TReq req, RequestHandlerDelegate<TRes> next, CancellationToken ct)
    {
        Console.WriteLine($"Handling {typeof(TReq).Name}");
        return await next(ct);
    }
}

cfg.AddOpenBehavior(typeof(LoggingBehavior<,>));

🧭 CQRS Done Right

Install:

dotnet add package Orchestrix.Mediator.Cqrs

Use:

public record SaveUser(string Name) : ICommand<Guid>;

public class SaveUserHandler : ICommandHandler<SaveUser, Guid>
{
    public ValueTask<Guid> Handle(SaveUser cmd, CancellationToken ct)
        => ValueTask.FromResult(Guid.NewGuid());
}

🔁 TrySend / TryPublish

bool handled = await sender.TrySend(new OptionalCommand());

bool published = await publisher.TryPublish(new OptionalEvent());

Avoid exceptions when no handler is found.

✨ Optional: Source Generator Boost

Install:

dotnet add package Orchestrix.Mediator.SourceGenerators

Add:

cfg.UseSourceGenerator();

No reflection. No runtime resolution. AOT-safe.

Orchestrix will emit a GeneratedDispatcher behind the scenes.

🧪 Fully Testable

var sender = new Mock<ISender>();
sender.Setup(s => s.Send(It.IsAny<IRequest<Guid>>(), It.IsAny<CancellationToken>()))
      .ReturnsAsync(Guid.NewGuid());

Use ISender, IPublisher, or IMediator in your tests.

🔁 Migrating from MediatR?

✅ Use the same patterns

✅ Replace IMediator with ISender/IPublisher

✅ Update AddMediatR to AddOrchestrix

✅ Replace INotificationHandler<T> with IParallelNotificationHandler<T> if needed

Read full migration guide → MIGRATION.md

📚 Resources

🔥 Ready to Modernize Mediation?

Whether you’re building a CQRS-heavy application, orchestrating event-driven flows, or simply want better observability — Orchestrix.Mediator is built to scale with you.

👉 Give it a ⭐ on GitHub: github.com/anzawi/Orchestrix.Mediator

💬 Feedback or questions? Drop them in the repo’s issues!

Implementing a Real-World Approval Workflow with Meridian (Part 2)

Mohammad Anzawi — Mon, 30 Jun 2025 02:16:36 +0000

🏢 Going Real-World with Meridian Workflow (Part 2)

Leave Approval System with Fluent API — Hooks, Validation, and REST API
Overview for the Workflow Engien: What Merdian Workflow
Part 1: Create a Leave Request Part 1 / choosing the right workflow-engine

In Part 1, we introduced the challenge of building business workflows and compared open-source engines. Among them was Meridian Workflow, a developer-first, type-safe engine for modeling approval flows in .NET 8.

In Part 2, we build a real-world Leave Request workflow using pure Fluent API — no templates or extensions (yet). This is the raw power of Meridian DSL.

🧠 In Part 3, we’ll refactor this using reusable TemplateExtensions and add attachment support for medical reports.

🧾 The Workflow

Employee submits a request
Supervisor reviews:
- If Days > 15, escalate to Section Head
Section Head reviews (if applicable)
HR gives final approval or rejection
Rejections trigger notifications
All transitions are auditable

📦 1. Workflow Data Model

public class LeaveRequestData : IWorkflowData
{
    public string EmployeeName { get; set; } = string.Empty;
    public LeaveTypes LeaveType { get; set; }
    public int Days { get; set; }
    public DateTime From { get; set; }
    public DateTime To { get; set; }
    public string Reason { get; set; } = string.Empty;
}

public enum LeaveTypes
{
    Annual,
    Sick,
    Unpaid,
    TimeOff
}

🪝 2. Hooks for Notifications and Logging

public class NewLeaveRequestCreated : IWorkflowHook<LeaveRequestData>
{
    public Task ExecuteAsync(WorkflowContext<LeaveRequestData> context)
    {
        Console.WriteLine($"📌 New request by {context.InputData?.EmployeeName}");
        return Task.CompletedTask;
    }
}

public class SendNotification(string source) : IWorkflowHook<LeaveRequestData>
{
    public Task ExecuteAsync(WorkflowContext<LeaveRequestData> context)
    {
        Console.WriteLine($"🔔 Notify {context.InputData?.EmployeeName} on {source}");
        return Task.CompletedTask;
    }
}

🧱 3. Workflow Definition Using Fluent API

public sealed class LeaveRequestWorkflow : IWorkflowBootstrapper
{
    public void Register(IWorkflowDefinitionBuilder builder)
    {
        builder.Define<LeaveRequestData>("LeaveRequestWorkflow", workflow =>
        {
            workflow.AddHook(new NewLeaveRequestCreated(), WorkflowHookType.OnRequestCreated);

            // State 1: Supervisor Review
            workflow.State("UnderDirectManagerReview", state =>
            {
                state.IsStart();

                state.Action("Approve", "UnderHRReview", action =>
                {
                    action.AssignToRoles("supervisor");

                    action.When(data => data.Days > 15, "UnderSectionHeadReview");

                    action.WithValidation(data =>
                    {
                        var errors = new List<string>();
                        if (string.IsNullOrWhiteSpace(data.Reason))
                            errors.Add("Reason is required.");
                        return errors;
                    });
                });

                state.Action("Reject", "Rejected", action =>
                {
                    action.AssignToRoles("supervisor");
                });
            });

            // State 2: Section Head Review
            workflow.State("UnderSectionHeadReview", state =>
            {
                state.AddHook(new SendNotification("Section Head"), cfg =>
                {
                    cfg.Mode = HookExecutionMode.Parallel;
                }, StateHookType.OnStateEnter);

                state.Action("Approve", "UnderHRReview", action =>
                {
                    action.AssignToRoles("sectionHead");
                });

                state.Action("Reject", "Rejected", action =>
                {
                    action.AssignToRoles("sectionHead");
                });
            });

            // State 3: HR Review
            workflow.State("UnderHRReview", state =>
            {
                state.Action("Approve", "Approved", action =>
                {
                    action.AssignToRoles("hr");
                    action.AddHook(new SendNotification("HR Approval"), cfg =>
                    {
                        cfg.Mode = HookExecutionMode.Parallel;
                        cfg.IsAsync = true;
                    });
                });

                state.Action("Reject", "Rejected", action =>
                {
                    action.AssignToRoles("hr");
                    action.AddHook(new SendNotification("HR Rejection"), cfg =>
                    {
                        cfg.Mode = HookExecutionMode.Parallel;
                    });
                });
            });

            // Final States
            workflow.State("Approved", state =>
            {
                state.IsCompleted();
                state.AddHook(new SendNotification("Final Approval"), cfg =>
                {
                    cfg.Mode = HookExecutionMode.Parallel;
                }, StateHookType.OnStateEnter);
            });

            workflow.State("Rejected", state =>
            {
                state.IsRejected();
                state.AddHook(new SendNotification("Final Rejection"), cfg =>
                {
                    cfg.Mode = HookExecutionMode.Parallel;
                }, StateHookType.OnStateEnter);
            });

            workflow.PrintToConsole();
        });
    }
}

🌐 4. Minimal REST API for Integration

builder.Services.AddMeridianWorkflow(options =>
{
    options.ConfigureDb(cfg => cfg.Use(db => db.UseInMemoryDatabase("WorkflowTestDb")));
    options.Workflows = [ new LeaveRequestWorkflow() ];
});

var currentUser = "admin";
var roles = new[] { "supervisor", "sectionHead", "hr" };

app.MapPost("/create", ([FromServices] IWorkflowService<LeaveRequestData> wf, [FromBody] LeaveRequestData req)
    => wf.CreateRequestAsync(req, currentUser));

app.MapPost("/action/{action}/{id}", ([FromServices] IWorkflowService<LeaveRequestData> wf, string action, Guid id)
    => wf.DoActionAsync(id, action, currentUser, roles, []));

app.MapGet("/request/{id}", ([FromServices] IWorkflowService<LeaveRequestData> wf, Guid id)
    => wf.GetRequestAsync(id));

app.MapPost("/tasks", ([FromServices] IWorkflowService<LeaveRequestData> wf)
    => wf.GetUserTasksAsync(currentUser, roles, []));

✅ Summary

In this article, we:

✅ Modeled a leave request approval flow
🔄 Created multi-role state transitions with conditions
🔌 Used hooks for logs and notifications
🧪 Added inline validations
🌐 Exposed REST APIs for frontend integration

This was built using raw Fluent API only — no abstraction, no templates.

🚀 Up Next: Part 3

In Part 3, we’ll:

♻️ Refactor using TemplateExtensions for DRY workflow definitions
📎 Add attachment support (e.g., medical reports)
🪝 Centralize validations, hooks, and task assignments
🧱 Prepare the workflow for scalable, multi-team usage

💬 What do you think?

Have you implemented approval workflows before?
Would you prefer the raw fluent API approach, or do you lean toward reusable templates?

Let me know how you'd structure your own leave request flow — or what you'd like to see covered in Part 3!

📎 Resources

Choosing the Right Workflow Engine for Business Approval Systems

Mohammad Anzawi — Sun, 15 Jun 2025 22:38:36 +0000

The Problem Space

Imagine implementing a typical Leave Request Workflow:

Employee submits a request (notify the direct manager).
Direct Manager approves or rejects (if rejected, notify the employee).
If approved and the leave duration exceeds 15 days, the Section Head must approve (send notification).
Regardless of previous outcomes, the request is sent to the HR department.
If approved by HR, the request is processed; if rejected, the employee is notified.
Audit logs are written at each step.

While this logic can be implemented using plain C#, as complexity increases—due to branching, retries, compensation, async calls—it becomes difficult to manage, maintain, and test. This is where workflow engines prove their value.

A workflow engine provides a structured, reusable way to model, execute, and manage business processes. Instead of hardcoding logic into services or controllers, workflow engines allow you to:

📋 Define states (e.g., Submitted, Approved, Rejected)
🔁 Configure transitions between states through actions or rules
👤 Handle human-driven steps, such as approvals or reviews
💾 Persist long-running workflows and resume execution later
🔍 Record audit logs for traceability and compliance

Workflow engines are ideal for scenarios like business approvals, employee onboarding, document lifecycles, and other multi-step decision-based processes.

Some engines are designed as general-purpose orchestrators. Others, like Meridian Workflow, are purpose-built for stateful, user-interactive workflows with strongly-typed fluent definitions.

You can either build your own workflow engine or use an existing open-source solution tailored to your needs.

Existing Workflow Engines at a Glance (Open Source)

A quick survey of popular open-source workflow engines yields several solid candidates:

Workflow Core -in github
Elsa Workflows - in github
Meridian Workflow - in github

Let’s explore the strengths and trade-offs of each, to help choose the right one.

Workflow Core

✅ Lightweight and C#-first.
❌ JSON-serialized persistence, lacking type safety during deserialization.
❌ No fluent API; workflows are defined by implementing interfaces.
❌ Refactoring is error-prone — issues appear at runtime rather than compile-time.

Elsa Workflows

✅ Rich feature set, visual designer, multiple persistence providers.
❌ Heavyweight — significant dependencies and steep learning curve.
❌ Workflow definitions use verbose JSON or C# models.
❌ Often overkill for simple state-based business logic.

Meridian Workflow

Meridian Workflow is designed specifically to fill the gap between simplicity and power:

💎 Pure C# DSL — workflows are defined entirely in C#, without JSON or visual designers.
✅ Compile-time safety — all input and output types are enforced by the compiler.
⚙️ Fluent API — simple chaining with .State(...), .Action(...), .When(...), .AddHook(...), etc.
⚡ Minimal overhead — no required UI, database, or service bus.
🛠 Easy testing — workflows can be executed in-memory and fully unit tested.

Feature Comparison Table

Feature	Meridian	Workflow Core	Elsa Workflows
Workflow Type	State-machine, approval-focused	Step-based, flow-oriented	Activity-based orchestration
Designer UI	❌ None	❌ None	✅ Visual Designer
DSL	✅ Fluent C# DSL	Fluent + JSON	JSON or verbose C#
Use Case Focus	Business approvals, human interactions	General-purpose workflows	Long-running orchestration, integrations
Task Handling	✅ Built-in (roles/users/groups)	❌ Requires custom logic	⚠️ Activity-based (not approval-centric)
Authorization	✅ Role/group/user-level authorization	❌ None built-in	⚠️ Not natively supported
Persistence Model	Built-in (lightweight)	Implicit persistence	Required
Approval Model	✅ Native support for actions, tasks, roles	❌ Not supported	⚠️ Requires workarounds
Extensibility	Hooks, templates, pluggable features	Middleware, step extensions	Extendable via activities/extensions
Developer Experience	✅ Zero-config, developer-first	❌ More boilerplate	❌ Heavy setup, advanced tooling required
Best Suited For	Leave requests, ticketing, approvals	General orchestrations	Workflow automation with integration needs
Attachment Handling	✅ Built-in file/attachment processing via pluggable `IWorkflowFileStorageProvider`	❌ Requires full custom implementation	⚠️ Supported via activities but not native

Conclusion

It’s clear that for state-machine, human-centric, or approval-based workflows, Meridian Workflow is the ideal choice.

It offers:

Clear, strongly-typed definitions
Built-in support for approvals and roles
Easy testing and minimal overhead
A developer-first experience

🚀 Bookmark-worthy?

If you ever revisit a workflow engine deep dive, this post might be one of those. Having it saved for when you're building approval flows could come in handy.

💬 Your turn

What’s been your toughest workflow challenge? Seeing your own use cases reflected here would help inform Part 2—and maybe spark ideas for others in the comments.

🔜 Coming soon: Part 2

We’ll be diving into setting up a Leave Request flow in Meridian Workflow—covering state definitions, approval actions, and transitions, step by step.

See you there!

Meridian Workflow – Build Type-Safe, Fluent Workflows in .NET +8 Without the Bloat

Mohammad Anzawi — Sun, 01 Jun 2025 23:51:20 +0000

🚀 Meridian Workflow – Build Type-Safe, Fluent Workflows in .NET 8 Without the Bloat

Workflows are everywhere — approvals, onboarding, document routing — but most engines are either overkill or too rigid.

Meridian Workflow is a lightweight, developer-first engine for .NET 8+ that gives you full control using clean, fluent, and type-safe definitions. No external dependencies. No XML. No drag-and-drop GUIs. Just powerful code.

🎯 Why Meridian?

Unlike legacy engines, Meridian is:

✅ Fluent & type-safe — define workflows in code with full IDE support
🧩 Pluggable — use hooks, custom logic, file providers, and task handlers
🔐 Secure — assign actions by user, role, or group
🧱 Clean — built Clean Architecture in mind
⚡ Zero-dependency — works in microservices or monoliths

Whether you're automating approvals or managing complex state transitions, Meridian gives you full control with minimal effort.

🚀 Quick Started in 5 Steps

1. Define Workflow Data Model

public class LeaveRequestData : IWorkflowData
{
    public string Reason { get; set; } = string.Empty;
    public int Days { get; set; }
}

2. Define the Workflow

public class LeaveRequestWorkflow : IWorkflowBootstrapper
{
    public void Register(IWorkflowDefinitionBuilder builder)
    {
        builder.Define<LeaveRequestData>("LeaveRequest", definition =>
        {
            definition.State("Pending", state =>
            {
                state.Action("Approve", "Approved");
                state.Action("Reject", "Rejected");
            });

            definition.State("Approved", state => state.IsCompleted());
            definition.State("Rejected", state => state.IsRejected());
        });
    }
  }

3. Register Meridian Workflow Engine

builder.Services.AddMeridianWorkflow(options =>
{
    options.Workflows =
    [
        new LeaveRequestWorkflow(),
    ];
});

4. Use the Engine

public class MyClass
{
    public MyClass(IWorkflowService<LeaveRequestData> leaveRequestWorkflow) 
    {
        // use the leaveRequestWorkflow to create, execute action, get history, get request, get logged-in user tasks, ...etc
    }
}

5. Visualize the Workflow (Optional)

workflowDefinition.PrintToConsole();

🔌 Plug Into Real-World Needs

Meridian comes with built-in support for:

Feature	Plug In With...
File Upload	`IWorkflowFileStorageProvider<TReference>`
Custom Business Logic	`IWorkflowHook<TData>`
Task Lifecycle	Auto-task generation per action
Action Authorization	Role/User/Group filters on each action
Auto Execution	Conditional auto-actions in workflow DSL

🧠 Hooks: Add Business Logic Cleanly

Purpose: Execute logic during request lifecycle (create, transition, entry/exit).
Types:
- Workflow Definition
- OnCreateHooks (When a new request is created)
- OnTransitionHooks (When request transitions)
- State
- OnEnterHooks (when request enters the state)
- OnExitHooks (when request exits the state)
- Action
- OnExecuteHooks (when user takes an action)

public class NotifyManager : IWorkflowHook<LeaveRequestData>
{
    public Task ExecuteAsync(WorkflowContext<LeaveRequestData> context)
    {
        Console.WriteLine("Notify: New request created.");
        return Task.CompletedTask;
    }
}

📎 Attach Files Without Complexity

public class LeaveRequestData : IWorkflowData
{
    public WorkflowFile<WorkflowFileAttachment> MedicalReport { get; set; } = new();
}

Implement your file storage like:

public interface IWorkflowFileStorageProvider<TReference>
{
    Task<TReference> UploadAsync(WorkflowFileAttachment attachment);
}

🛠 Use Cases

📅 Leave requests with multi-step approvals
🧾 Document reviews with file uploads
🛠 Support tickets with escalation and SLA
🧑‍💼 HR onboarding with task delegation
🧠 Any domain requiring state + logic + history > AND MORE...!

🌟 Ready to Try It?

📖 See full documentation and deep-dive examples in the GitHub README

📦 NuGet: Coming soon — follow the repo to get notified

⭐ Star the project to support its growth!

👏 Contributing

Want to help?

Submit hooks, templates, and advanced samples
Improve test coverage
Build roadmap features like timeout, delegation, or JSON DSL
Report bugs or usability improvements

🧪 Unit tests are still in progress — help is appreciated!

📄 License

Apache License 2.0 — free for use in open-source and commercial apps.