Genocs.Messaging.Outbox.MongoDB Agent Reference

This document is optimized for AI-assisted development sessions.

Genocs.Messaging.Outbox.MongoDB Agent Reference

Purpose

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

  • What Genocs.Messaging.Outbox.MongoDB 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.MongoDB
Project filesrc/Genocs.Messaging.Outbox.MongoDB/Genocs.Messaging.Outbox.MongoDB.csproj
Target frameworksnet10.0, net9.0, net8.0
Primary roleMongoDB-backed implementation of outbox/inbox storage and initialization for Genocs.Messaging.Outbox
Core themesAddMongo configurator extension, MongoMessageOutbox implementation, Mongo TTL indexes, message serialization/deserialization, optional transaction support

Use This Package When

  • Persisting outbox and inbox records in MongoDB.
  • Replacing in-memory outbox storage with durable collections.
  • Enabling TTL cleanup for processed inbox/outbox records.
  • Using Mongo transaction boundaries during inbox deduplication and handler execution.
  • Wiring outbox repositories through Genocs.Persistence.MongoDB.

Do Not Assume

  • This package does not register outbox by itself; it extends IMessageOutboxConfigurator and must be used from AddMessageOutbox.
  • Transactions are disabled when outbox disableTransactions option is true.
  • Message and messageContext runtime types must be resolvable at deserialization time from saved assembly-qualified type names.

High-Value Entry Points

Configurator integration

Outbox implementation

Initialization and indexes

Core models and options consumed

Integration usage reference

Decision Matrix For Agents

GoalPreferred APINotes
Switch outbox storage to MongoDBAddMessageOutbox(o => o.AddMongo())Runs from base outbox package configurator
Use custom collection namesOutboxOptions.InboxCollection and OutboxOptions.OutboxCollectionDefaults are inbox and outbox
Enable TTL cleanupOutboxOptions.Expiry > 0Initializer creates ProcessedAt TTL indexes
Enable transactional inbox handlingKeep DisableTransactions falseWraps handler plus inbox add in session transaction
Disable transactional handlingSet DisableTransactions trueSkips session and transaction calls
Save outbound message durablyIMessageOutbox.SendAsync on MongoMessageOutboxStores serialized payload and type metadata
Rehydrate pending unsent messagesIMessageOutboxAccessor.GetUnsentAsyncDeserializes message and messageContext
Mark records as processedIMessageOutboxAccessor.ProcessAsyncUpdates ProcessedAt in Mongo collection

Minimal Integration Recipe

Install 

dotnet add package Genocs.Messaging.Outbox.MongoDB

Setup in Program.cs 

using Genocs.Core.Builders;
using Genocs.Messaging.Outbox;
using Genocs.Messaging.Outbox.MongoDB;
using Genocs.Persistence.MongoDB.Extensions;

var builder = WebApplication.CreateBuilder(args);

IGenocsBuilder gnxBuilder = builder.AddGenocs();

gnxBuilder
    .AddMongo()
    .AddMessageOutbox(o => o.AddMongo());

gnxBuilder.Build();

var app = builder.Build();

app.Run();

Behavior Notes That Affect Agent Decisions

  • AddMongo registers Mongo repositories for InboxMessage and OutboxMessage.
  • AddMongo adds a BsonClassMap for OutboxMessage and unmaps Message and MessageContext object members.
  • HandleAsync checks duplicate inbox message ID before running handler.
  • Transaction commit/abort happens only when transactions are enabled.
  • SendAsync serializes message and message context into JSON strings and stores runtime type names.
  • GetUnsentAsync deserializes persisted JSON back into runtime objects based on saved type metadata.

Source-Accurate Capability Map

Mongo registration layer

  • Resolves collection names from options with inbox/outbox defaults.
  • Registers Mongo repositories for inbox and outbox entities.
  • Registers Mongo outbox services for both IMessageOutbox and accessor interface.
  • Registers initializer for TTL index provisioning.

Files:

Durable outbox and inbox processing

  • Implements idempotent inbound handling via inbox repository existence check.
  • Stores outgoing message metadata and serialized payload in outbox repository.
  • Supports optional transaction around handler plus inbox insert.
  • Logs processing and storage warnings when disabled.

Files:

Pending message rehydration and completion

  • Retrieves unsent messages by ProcessedAt equals null.
  • Rehydrates Message and MessageContext from serialized JSON and type names.
  • Marks single or multiple records processed via update operations.

Files:

TTL index initialization

  • Creates TTL index for inbox ProcessedAt when expiry is configured.
  • Creates TTL index for outbox ProcessedAt when expiry is configured.
  • Skips index creation when outbox is disabled or expiry is non-positive.

Files:

Shared model and option contracts

  • Uses OutboxOptions for enabled flag, expiry, transaction toggle, and collection names.
  • Reuses shared inbox/outbox message entities from base outbox package.

Files:

Practical integration reference

  • Demonstrates AddMessageOutbox with AddMongo in demo host setup.

Files:

Dependencies

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

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