Genocs.Messaging.Outbox Agent Reference

This document is optimized for AI-assisted development sessions.

Genocs.Messaging.Outbox Agent Reference

Purpose

This document is optimized for AI-assisted development sessions. It prioritizes fast retrieval of:

  • What Genocs.Messaging.Outbox is responsible for
  • Which APIs to call for specific goals
  • Where source of truth lives
  • What constraints and runtime behaviors matter

Quick Facts

KeyValue
PackageGenocs.Messaging.Outbox
Project filesrc/Genocs.Messaging.Outbox/Genocs.Messaging.Outbox.csproj
Target frameworksnet10.0, net9.0, net8.0
Primary roleOutbox pattern abstraction and hosted processor for reliable publish and idempotent message handling
Core themesAddMessageOutbox registration, IMessageOutbox abstraction, in-memory outbox, periodic flush processor, inbox/outbox records

Use This Package When

  • Buffering outbound bus messages before publish.
  • Applying idempotent processing for inbound messages via message IDs.
  • Running periodic outbox flush logic as a hosted service.
  • Selecting outbox implementation via configurator extensions.
  • Sharing a transport-agnostic outbox abstraction across messaging backends.

Do Not Assume

  • AddMessageOutbox only starts processing when outbox options are enabled.
  • Default configurator behavior is in-memory outbox when no custom configure action is provided.
  • Header assignment in SendAsync expects a Dictionary<string, object> at runtime; non-dictionary IDictionary input can fail with cast errors.

High-Value Entry Points

Registration and configuration

Outbox abstraction contracts

Hosted processing flow

In-memory implementation

Message persistence models

Integration usage reference

Decision Matrix For Agents

GoalPreferred APINotes
Enable outbox featureAddMessageOutboxReads outbox options and wires processor/services
Use default implementation quicklyAddMessageOutbox with no configure delegateAutomatically calls AddInMemory
Select in-memory outbox explicitlyAddInMemoryRegisters InMemoryMessageOutbox as IMessageOutbox
Save outbound message with metadataIMessageOutbox.SendAsyncStores message payload, context, IDs, headers, timestamps
Process incoming message idempotentlyIMessageOutbox.HandleAsyncUses inbox marker to skip duplicates
Pull pending unsent recordsIMessageOutboxAccessor.GetUnsentAsyncUsed by hosted processor
Mark one message processedIMessageOutboxAccessor.ProcessAsync(OutboxMessage)Used in sequential mode
Mark many messages processedIMessageOutboxAccessor.ProcessAsync(IEnumerable)Used in parallel mode

Minimal Integration Recipe

Install 

dotnet add package Genocs.Messaging.Outbox

Setup in Program.cs 

using Genocs.Core.Builders;
using Genocs.Messaging.Outbox;

var builder = WebApplication.CreateBuilder(args);

IGenocsBuilder gnxBuilder = builder.AddGenocs();

gnxBuilder.AddMessageOutbox();

gnxBuilder.Build();

var app = builder.Build();

app.Run();

Behavior Notes That Affect Agent Decisions

  • AddMessageOutbox uses registry key messageBrokers.outbox and ignores duplicate registration.
  • OutboxProcessor validates interval milliseconds and throws when enabled with non-positive interval.
  • OutboxProcessor supports sequential and parallel processing modes via outbox type option.
  • In sequential mode, each message is marked processed immediately after publish.
  • In parallel mode, all published messages are marked processed in one batch.
  • InMemoryMessageOutbox removes expired processed records only when expiry is greater than zero.

Source-Accurate Capability Map

Registration and lifecycle

  • Reads options from configurable section with default key outbox.
  • Registers options singleton and implementation services.
  • Auto-adds hosted outbox processor when enabled.
  • Supports extension-based implementation choice.

Files:

Abstraction layer

  • Defines enabled state and methods for inbox handling and outbound buffering.
  • Defines accessor methods for unsent retrieval and processed marking.
  • Exposes configurator bridge to builder and options.

Files:

Hosted dispatch processing

  • Periodically reads unsent records from accessor.
  • Publishes records through IBusPublisher.
  • Applies sequential or batch processed marking strategy.
  • Uses DI scope per processing iteration.

Files:

In-memory storage behavior

  • Uses concurrent dictionaries for inbox and outbox state.
  • Implements duplicate detection for inbound IDs.
  • Stores outbound payload and metadata in OutboxMessage.
  • Removes processed records after expiry window.

Files:

Message entity models

  • Outbox entity stores serialized/raw payload metadata and lifecycle timestamps.
  • Inbox entity stores processed marker and timestamp.
  • Both entities implement IEntity.

Files:

Practical integration reference

  • Demonstrates AddMessageOutbox with Mongo implementation selection.

Files:

Dependencies

From src/Genocs.Messaging.Outbox/Genocs.Messaging.Outbox.csproj:

  • Genocs.Messaging
Last modified on March 21, 2026
Edit this page on GitHub
← Genocs.Messaging Agent Reference
Genocs.Messaging.Outbox.MongoDB Agent Reference →