Genocs.Messaging.Outbox

Genocs.Messaging.Outbox — Agent Reference Documentation

Consumer Mode for Agents

  • Assume package is installed from NuGet.
  • Do not rely on repository source code access.
  • Prefer stable public APIs and extension methods documented here.
  • If behavior is uncertain, fail safely and request config/package version details.

Purpose

Genocs.Messaging.Outbox provides outbox abstractions and a background processor for reliable outbound publish and idempotent inbound handling.

Quick Facts

KeyValue
PackageGenocs.Messaging.Outbox
Target frameworksnet10.0, net9.0, net8.0
Primary roleOutbox abstraction and processing runtime
Core entry pointsAddMessageOutbox, AddInMemory, IMessageOutbox, IMessageOutboxAccessor

Install 

dotnet add package Genocs.Messaging.Outbox

Minimal Integration Recipe (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();

Configuration

Use the outbox section.

{
  "outbox": {
    "enabled": true,
    "expiry": 3600,
    "intervalMilliseconds": 5000,
    "inboxCollection": "inbox",
    "outboxCollection": "outbox",
    "type": "sequential",
    "disableTransactions": false
  }
}
SettingTypeDescription
enabledboolEnables the outbox runtime and hosted processing loop.
expiryintExpiry window used by providers that support processed-message cleanup.
intervalMillisecondsdoublePolling interval used by the background processor. Must be positive when processing is enabled.
inboxCollectionstringInbox storage name used by durable providers such as MongoDB.
outboxCollectionstringOutbox storage name used by durable providers such as MongoDB.
typestringProcessing strategy hint used by the runtime, for example sequential versus batch-style processing.
disableTransactionsboolDisables transaction usage for providers that support transactional handling.

For simple in-memory usage, only enabled and intervalMilliseconds are typically required. Collection and transaction settings become relevant when you add a durable provider.

Decision Matrix For Agents

GoalPreferred API
Enable outbox with default storageAddMessageOutbox()
Select explicit in-memory providerAddMessageOutbox(o => o.AddInMemory())
Buffer outbound message before publishIMessageOutbox.SendAsync(...)
Enforce idempotent inbound handlingIMessageOutbox.HandleAsync(...)
Retrieve and mark pending outbox recordsIMessageOutboxAccessor.GetUnsentAsync() and ProcessAsync(...)

Behavior Notes / Constraints

  • Outbox background processing starts only when enabled by configuration.
  • Processing interval must be positive when outbox processing is enabled.
  • In-memory provider is non-durable and suited for development or simple single-instance scenarios.

Public Capability Map

  • Outbox registration through AddMessageOutbox.
  • Provider selection through the outbox configurator.
  • Outbound buffering and inbound deduplication via IMessageOutbox.
  • Pending-record retrieval and processed marking via IMessageOutboxAccessor.

Dependencies

  • Genocs.Messaging
  • Optional durable provider package for production usage

Troubleshooting

  1. Outbox processor never starts. Fix: Set outbox.enabled to true and configure a positive outbox.intervalMilliseconds value.
  2. Messages disappear after service restart. Fix: Replace in-memory outbox storage with a durable outbox provider.
  3. Duplicate inbound processing still occurs. Fix: Call HandleAsync with stable message identifiers for each consumed message.
Last modified on March 24, 2026
Edit this page on GitHub
← Genocs.Messaging
Genocs.Messaging.Outbox.MongoDB →