Home

Introduction

What is LiteBus?

LiteBus is a lightweight, high-performance, in-process mediator for .NET applications, designed to help you implement Command Query Separation (CQS) and build clean, maintainable, and scalable systems. It provides a structured, decoupled architecture for handling commands, queries, and events.

Its design is guided by Domain-Driven Design (DDD) principles, offering a rich and semantic API that keeps your business logic isolated from infrastructure concerns.

Core Concepts

LiteBus is built around three fundamental message types, aligning with the CQS pattern.

Commands

Commands represent an intention to change the system's state (e.g., CreateProductCommand).

• Handled by exactly one handler.
• Can return a result (ICommand<TResult>) or be void (ICommand).
• Can be processed durably and asynchronously via the Command Inbox.

Queries

Queries are requests to retrieve data without modifying state (e.g., GetProductByIdQuery).

• Handled by exactly one handler.
• Always return data, either as a single result (IQuery<TResult>) or a stream (IStreamQuery<TResult>).
• Should be side-effect free.

Events

Events are notifications that something significant has occurred in the system (e.g., OrderShipped).

• Can be handled by zero, one, or many handlers.
• Do not return a value.
• Support Plain Old CLR Objects (POCOs), allowing you to publish domain events without framework dependencies.

Key Features

• DI Agnostic: A decoupled runtime with adapters for Microsoft DI and Autofac.
• High Performance: Minimal reflection at runtime, with cached handler resolution.
• Durable Command Inbox: Guaranteed, at-least-once command processing for critical operations.
• Advanced Event Mediation: Granular control over event handler execution, including priority groups and configurable concurrency (Sequential vs. Parallel).
• Rich Handler Pipeline: First-class support for pre-handlers, post-handlers, and error handlers for every message type.
• Flexible Handler Filtering: Selectively execute handlers using static [HandlerTag] attributes or dynamic HandlerPredicate functions.
• Modern C# Support: Built for .NET 8+ with full support for records, init properties, and nullable reference types.
• Advanced Type System Support:
  • Polymorphic Dispatch: Handlers for base types can process derived messages.
  • Generic Messages & Handlers: Create reusable components for common operations.

Architectural Overview

LiteBus is composed of independent but interoperable modules that you can adopt as needed.

• LiteBus.Runtime: The core, DI-agnostic layer that manages modules and dependencies.
• LiteBus.Messaging: The foundational module providing the core IMessageMediator and handler resolution logic.
• LiteBus.Commands: Adds support for state-changing commands and the durable inbox.
• LiteBus.Queries: Adds support for data retrieval queries and streams.
• LiteBus.Events: Adds support for publish-subscribe eventing with advanced mediation.