EricksonLopez.Outbox.SourceGenerators 1.0.0

EricksonLopez.Outbox

A high-performance, cloud-native, and zero-allocation oriented implementation of the Transactional Outbox and Idempotent Inbox patterns for .NET.

The Transactional Outbox pattern ensures that the creation or modification of a domain model and the publishing of the corresponding event to a Message Broker (e.g., RabbitMQ, Kafka) are performed as an atomic operation, avoiding the dreaded "Dual Write Problem".

The Idempotent Inbox pattern protects your consumers from executing business logic twice in the event that the Message Broker delivers the same message more than once (At-Least-Once Delivery).

⚡ Performance

BenchmarkDotNet v0.13.12 · .NET 10.0.10 (10.0.1026.32716) · X64 RyuJIT AVX-512F+CD+BW+DQ+VL+VBMI · Windows 11 (10.0.26200.8875)

Storage: InMemory (isolates framework CPU/GC overhead from network I/O). See full methodology.

vs. Industry Competitors — StoreAsync (single message)

Serialization — IBufferWriter<byte> vs allocating path

Concurrency — Parallel StoreAsync (linear scaling up to 64 threads)

Type Resolution (FrozenDictionary — O(1) zero-alloc)

Key takeaways:

• 3.3× faster and 73% less memory than CAP in store operations.
• 99× faster and 92% less memory than NServiceBus.
• IBufferWriter<byte> serialization path allocates only 32 B regardless of payload size — a 94–99.97% memory reduction vs the allocating path.
• Type resolution is zero-allocation at ~1–2 nanoseconds via FrozenDictionary.
• Scales linearly to 64 concurrent threads with zero lock contention on the store path.

→ Full benchmark results and methodology · Performance tuning guide

Key Features

• Guaranteed Atomicity: Seamless integration with ADO.NET transactions (DbTransactionContext) and Entity Framework Core.
• Extreme Performance: Optimized with ReadOnlyMemory<T>, ValueTask, and array pooling for serialization to reduce Gen 0 garbage collection.
• AOT Ready: Native support for Ahead-Of-Time (Native AOT) compilation via System.Text.Json Source Generators. Zero runtime reflection.
• Adaptive Dispatcher: Dynamic polling that reduces frequency when there is no load (Adaptive Polling) to prevent database saturation, using SKIP LOCKED for multi-instance horizontal scalability.
• Circuit Breaker & Retry Policies: Robust fault tolerance strategies using ExponentialBackoffPolicy.
• Built-in Idempotency: Native de-duplication of incoming messages via the Inbox daemon.
• Broker Abstraction: Decoupled from the transport layer. Send messages to RabbitMQ, Kafka, Azure Service Bus, AWS SQS, Google Pub/Sub, NATS, or Redis Streams.

Ecosystem Packages

Package	Description	NuGet
EricksonLopez.Outbox	Core interfaces, dispatcher, and base logic
EricksonLopez.Outbox.EntityFrameworkCore	Native integration for EF Core
EricksonLopez.Outbox.MassTransit	MassTransit integration
EricksonLopez.Outbox.Storage.PostgreSql	PostgreSQL native storage provider
EricksonLopez.Outbox.Storage.SqlServer	SQL Server native storage provider
EricksonLopez.Outbox.Storage.MySql	MySQL native storage provider
EricksonLopez.Outbox.Storage.Oracle	Oracle native storage provider
EricksonLopez.Outbox.Storage.Sqlite	SQLite native storage provider
EricksonLopez.Outbox.Brokers.RabbitMQ	RabbitMQ physical publisher
EricksonLopez.Outbox.Brokers.Kafka	Kafka physical publisher
EricksonLopez.Outbox.Brokers.AzureServiceBus	Azure Service Bus publisher
EricksonLopez.Outbox.Brokers.AwsSqs	AWS SQS physical publisher
EricksonLopez.Outbox.Brokers.GooglePubSub	Google Pub/Sub publisher
EricksonLopez.Outbox.Brokers.Nats	NATS physical publisher
EricksonLopez.Outbox.Brokers.RedisStreams	Redis Streams publisher
EricksonLopez.Outbox.SourceGenerators	Compile-time type mapping generator
EricksonLopez.Outbox.Analyzers	Roslyn analyzers for correct outbox usage

.NET Framework Support Policy

All library packages target net8.0, net9.0, and net10.0. Analyzers and SourceGenerators target netstandard2.0.

Support Policy: This library supports only .NET frameworks with active official support from Microsoft. A framework version is included in TargetFrameworks as long as it appears on the Microsoft .NET Support Policy page under Active or Maintenance status. Framework versions are removed from TargetFrameworks when they reach their official end-of-life date as defined by Microsoft — not before, and not after.

Framework	Type	Microsoft Support End Date	Status
.NET 8	LTS	November 10, 2026	✅ Supported
.NET 9	STS	November 10, 2026	✅ Supported
.NET 10	LTS	November 2028	✅ Supported

Quick Start

1. Install the core package and a storage provider:

   dotnet add package EricksonLopez.Outbox
   dotnet add package EricksonLopez.Outbox.Storage.PostgreSql
   

2. Configure services in your Program.cs:

   builder.Services.AddOutbox(options =>
   {
       // 1. Use Source Generators for JSON serialization
       options.UseSerializer(new NativeAotJsonSerializer(OutboxJsonContext.Default));
       // 2. Resolve type mapping for AOT
       options.UseGeneratedTypes(); 
   });
   
   // 3. Register the Database Repository
   builder.Services.AddScoped<IOutboxRepository, PostgreSqlOutboxRepository>();
   
   // 4. Start the Background Daemons
   builder.Services.AddOutboxDispatcher(options =>
   {
       options.BatchSize = 100;
       options.UseAdaptivePolling = true;
   });
   

Documentation

Contributing

See CONTRIBUTING.md for information on building the project, running tests, and contributing guidelines.

Security

Please review SECURITY.md for details on our security policies and how to report vulnerabilities.

Code of Conduct

We follow the Contributor Covenant. See CODE_OF_CONDUCT.md for details.

License

This project is licensed under the MIT License — see the LICENSE file for details.