LiteBus Documentation
This directory contains the authoritative LiteBus documentation. Pages are versioned with the source, reviewed with API changes, and validated by the repository build. The former GitHub wiki is not a documentation source for v6.
LiteBus v6 targets .NET 10 and remains unreleased. A page that describes a v6 API defines the current branch contract, not a compatibility promise for an earlier package version.
The Fumadocs pages under site/content/docs mirror this tree. The documentation site content
gate compares every page byte-for-byte and rejects missing, stale, or orphaned copies. The
root v7 roadmap is mirrored under the site's roadmap section by the same gate.
Directory Layout
| Directory | Content |
|---|---|
getting-started/ | Installation, first application, working conventions, and recipes |
concepts/ | Mediator contracts, handlers, execution context, and dispatch behavior |
architecture/ | Layering, package dependencies, API rules, decisions, and hosting model |
reliable-messaging/ | Inbox, outbox, saga, transaction, and delivery semantics |
integrations/ | Broker, ingress, dispatch, storage, and schema adapter guides |
operations/ | Diagnostics, security, performance, runbook, and troubleshooting guidance |
testing/ | Application testing, repository test suites, and integration categories |
reference/ | Capability inventory, analyzer rules, feature index, and glossary |
extending/ | Custom modules, stores, dispatchers, and framework adapters |
migration/ | Version upgrades and MediatR migration guidance |
roadmap/ | Deferred work and accepted v6 limits |
contributing/ | Repository contribution workflow |
catalog/ | Contract-level capability pages grouped by LiteBus subsystem |
Start Here
| Goal | Page |
|---|---|
| Install LiteBus and run the first handler | Getting Started |
| Run a compile-checked application | LiteBus Sample |
| Select packages without widening dependencies | Dependency Graph |
| Review the full v6 feature inventory | v6 Feature Index |
| Find a contract, builder method, or adapter by capability | Capability Catalog |
| Understand generated inventories and executable documentation checks | Documentation Semantic Validation |
| Upgrade an application to v6 | Migration Guide v6 |
| Diagnose a configuration or runtime failure | Troubleshooting |
Architecture and API Design
- Architecture defines dependency roles, module registration, manifests, durable processing, and telemetry boundaries.
- Dependency Graph lists package roles and direct references.
- API Design defines semantic input types, metadata variants, method shapes, and naming rules.
- Architecture Decisions records decisions that constrain future work.
- Extensibility covers custom modules, stores, dispatchers, and host adapters.
Mediator
| Area | Primary Guide | Detailed Catalog |
|---|---|---|
| Commands | Command Module | Command Catalog |
| Queries and streaming | Query Module | Query Catalog |
| Events and concurrency | Event Module | Event Catalog |
| Handler stages | Handler Pipeline | Pipeline Catalog |
| Runtime selection | Handler Filtering | Filtering Catalog |
| Type resolution | Polymorphic Dispatch | Resolution Catalog |
| Open generic handlers | Open Generic Handlers | Open Generic Catalog |
Inbox and Outbox
Read Reliable Messaging Semantics before selecting a durable topology.
| Area | Guide | Detailed Catalog |
|---|---|---|
| Inbox acceptance and execution | Inbox | Inbox Acceptance and Inbox Processor |
| Outbox enqueue and publication | Outbox | Outbox Enqueue and Outbox Processor |
| Atomic application writes | Transactional Messaging Writes | Transactional Writes Catalog |
| Retry, lease, and dead-letter behavior | Reliable Messaging | Lease, Retry, and Dead Letter |
| Operations | Operations and Management | Operations Catalog |
Storage
| Adapter | Inbox | Outbox | Shared Infrastructure |
|---|---|---|---|
| PostgreSQL | LiteBus.Inbox.Storage.PostgreSql | LiteBus.Outbox.Storage.PostgreSql | PostgreSQL Schema Management |
| Entity Framework Core | Inbox EF Core Storage | Outbox EF Core Storage | EF Core Storage Catalog |
| In-memory | LiteBus.Inbox.Storage.InMemory | LiteBus.Outbox.Storage.InMemory | Test and local behavior use only |
The Storage Catalog maps store roles to each adapter implementation.
Transport, Dispatch, and Ingress
Transport publishes and consumes wire envelopes. Dispatch maps a leased inbox or outbox envelope to a transport. Ingress maps a consumed transport envelope into inbox acceptance.
| Broker | Transport | Dispatch | Ingress | v6 Classification |
|---|---|---|---|---|
| AMQP | AMQP Transport | Inbox and outbox | AMQP Ingress | Release target |
| Kafka | Kafka Transport | Inbox and outbox | Kafka ingress | Ingress remains prerelease pending broader failure testing |
| AWS SQS | AWS SQS Transport | Inbox and outbox | AWS SQS ingress | Prerelease pending live-service certification |
| Azure Service Bus | Azure Service Bus Transport | Inbox and outbox | Azure Service Bus ingress | Prerelease pending live-service certification |
| In-memory | Transport test implementation | Inbox and outbox | In-memory ingress | Testing support |
The Transport, Dispatch, and Ingress catalogs document wire mapping, acknowledgement, retry, and registration behavior.
Hosting, Diagnostics, and Telemetry
- Hosted Services defines startup tasks, background services, diagnostic checks, and host manifests.
- Diagnostics and Health defines framework-neutral checks and ASP.NET Core health integration.
- Production Runbook covers startup, shutdown, failed-message operations, and schema ownership.
- Security and Tenancy covers tenant isolation and payload protection boundaries.
- Hosting Catalog lists Microsoft DI, Autofac, ASP.NET Core, health, and OpenTelemetry adapters.
Saga Extension
Saga documents correlated inbox state, optimistic concurrency, tenant scoping, and store selection. The feature is an inbox extension, not a general workflow engine. The Saga Catalog lists each contract and integration point.
Testing and Operations
- Testing covers unit and component test patterns.
- Testing LiteBus covers application tests and mediator replacement.
- Integration Tests maps broker, storage, hosting, and end-to-end suites to CI categories.
- Performance Considerations records allocation and concurrency constraints.
- Analyzers lists compile-time diagnostics and their v6 behavior.
- Documentation Semantic Validation defines generated inventories, compiled snippets, and executable claim anchors.
Reference
Documentation Checks
Run the same repository check used by CI:
pwsh ./scripts/Test-Documentation.ps1The check rejects broken relative links, links that escape the repository, wiki references, trailing whitespace, banned Unicode typography, and phrases prohibited by the repository writing rules.