Home

Introduction

What is LiteBus?

LiteBus is a lightweight, in-process mediator implementing Command Query Separation (CQS) patterns in .NET applications. It provides a structured approach to handling commands, queries, and events.

Key characteristics:

• Developed for .NET 8
• No external dependencies
• Reduced reflection usage
• Polymorphic message dispatch with covariance/contravariance support
• Modular architecture with separated abstractions and implementations

Core Concepts

Commands

Commands request system state changes:

• Single handler per command type
• Can be result-producing (ICommand<TResult>) or void (ICommand)
• Processed exactly once
• Named with imperative verbs (e.g., CreateProductCommand)

Queries

Queries retrieve data without changing state:

• Single handler per query type
• Always return results (IQuery<TResult>) or result streams (IStreamQuery<TResult>)
• Side-effect free
• Named with noun phrases (e.g., GetProductQuery)

Events

Events notify about system occurrences:

• Multiple handlers allowed (or none)
• No required return value
• Asynchronous processing
• Named with past tense verbs (e.g., ProductCreatedEvent)
• Can use POCO objects without framework interfaces

Mediator Pattern

LiteBus implements the Mediator pattern to decouple components by channeling communication through mediators:

• Message senders don't need direct handler references
• Handlers focus on specific tasks
• Pipeline processing with pre/post/error handling capabilities

Key Features

Message Types

• ICommand / ICommand<TResult>: State-changing operations
• IQuery<TResult>: Data retrieval operations
• IStreamQuery<TResult>: Stream-based data retrieval
• IEvent: Notifications

Handler Features

• Pre-handlers for validation, logging, enrichment
• Post-handlers for notifications, cleanup
• Error handlers for exception management
• Covariant type handling for inheritance hierarchies
• Handler ordering control
• Tag-based handler filtering

Execution Features

• Contextual data sharing between handlers
• Execution flow control (abort capabilities)
• Cancellation support

Integration

• Microsoft Dependency Injection support
• Assembly scanning for automatic registration

Architectural Overview

Module Structure

• Command Module: State-changing operations
• Query Module: Data retrieval operations
• Event Module: Notification broadcasting
• Messaging Module: Core foundation for all types

Message Processing Flow

1. Message sent to mediator
2. Pre-handlers execute
3. Main handler processes message
4. Post-handlers execute
5. Error handlers catch exceptions
6. Result returned (if applicable)