Genocs.Saga.Integrations.MongoDB Agent Reference

This document is optimized for AI-assisted development sessions.

Genocs.Saga.Integrations.MongoDB Agent Reference

Purpose

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

  • What Genocs.Saga.Integrations.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.Saga.Integrations.MongoDB
Project filesrc/Genocs.Saga.Integrations.MongoDB/Genocs.Saga.Integrations.MongoDB.csproj
Target frameworksnet10.0, net9.0, net8.0
Primary roleMongoDB-backed saga state and log persistence implementation for Genocs.Saga
Core themesUseMongoPersistence extensions, SagaMongoOption config, MongoSagaStateRepository, MongoSagaLog

Use This Package When

  • Persisting saga state and saga logs into MongoDB collections.
  • Replacing default in-memory saga persistence with durable storage.
  • Configuring saga Mongo persistence from app configuration.
  • Passing explicit Mongo settings in tests or controlled environments.
  • Sharing saga persistence across multiple application instances.

Do Not Assume

  • UseMongoPersistence requires Genocs.Saga AddSaga registration; this package does not register saga coordinator pipeline by itself.
  • Configuration overload throws SagaException when settings deserialization/access fails.
  • Mongo persistence uses fixed collection names SagaData and SagaLog.

High-Value Entry Points

Integration registration

Configuration model

Mongo persistence implementations

Core saga abstractions consumed

Decision Matrix For Agents

GoalPreferred APINotes
Enable Mongo persistence via configurationUseMongoPersistence(builder, IConfiguration)Reads SagaMongo section using SagaMongoOption.Position
Enable Mongo persistence with explicit settingsUseMongoPersistence(builder, SagaMongoOption)Best for tests and explicit startup wiring
Persist saga state snapshotISagaStateRepository.WriteAsync via MongoSagaStateRepositoryReplaces existing document by saga ID and type then inserts new state
Load saga state for rehydrationISagaStateRepository.ReadAsync via MongoSagaStateRepositoryReturns first state doc matching saga ID and saga type
Persist saga log entryISagaLog.WriteAsync via MongoSagaLogAppends message entry to SagaLog collection
Read compensation historyISagaLog.ReadAsync via MongoSagaLogReads all log rows for saga ID and type
Set custom Mongo database connectionSagaMongoOption.ConnectionString and DatabasePassed to MongoClient and GetDatabase
Replace storage provider without changing saga coreISagaBuilder.UseSagaLog and UseSagaStateRepository calls in extensionPackage binds both interfaces to Mongo implementations

Minimal Integration Recipe

Install 

dotnet add package Genocs.Saga.Integrations.MongoDB

Setup in Program.cs 

using Genocs.Saga;
using Genocs.Saga.Integrations.MongoDB;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSaga(saga =>
{
    saga.UseMongoPersistence(builder.Configuration);
});

var app = builder.Build();

app.Run();

Configuration 

{
  "SagaMongo": {
    "ConnectionString": "mongodb://localhost:27017",
    "Database": "genocs_saga"
  }
}

Behavior Notes That Affect Agent Decisions

  • Configuration-based registration catches failures and throws SagaException with a generic deserialization error message.
  • The integration registers IMongoDatabase through a transient factory delegate.
  • State writes are implemented as delete-then-insert, not atomic update.
  • Saga type identity is persisted as Type.FullName string and used for filtering reads.
  • MongoSagaState resolves runtime Type by scanning loaded AppDomain assemblies.
  • MongoSagaLogData resolves ISagaLogData.Type from Assembly.GetEntryAssembly(), which can be null in some host/test scenarios.

Source-Accurate Capability Map

Builder integration and wiring

  • Extends ISagaBuilder with Mongo persistence overloads.
  • Supports both IConfiguration-driven and explicit option-driven setup.
  • Registers Mongo-backed implementations for saga log and state repository.

Files:

Saga state persistence in MongoDB

  • Stores state records in SagaData collection.
  • Reads by saga ID and saga type full name.
  • Persists state object payload and saga state enum values.

Files:

Saga log persistence in MongoDB

  • Stores message logs in SagaLog collection.
  • Reads log stream for specific saga ID and saga type.
  • Persists created-at timestamp and original message payload.

Files:

Core saga contract interoperability

  • Integrates through ISagaBuilder customization hooks.
  • Implements ISagaStateRepository and ISagaLog contracts expected by Genocs.Saga managers.

Files:

Dependencies

From src/Genocs.Saga.Integrations.MongoDB/Genocs.Saga.Integrations.MongoDB.csproj:

  • Genocs.Core (project reference in Debug, package reference in Release)
  • Genocs.Saga (project reference in Debug, package reference in Release)
  • Microsoft.Extensions.Configuration
  • MongoDB.Driver
Last modified on March 21, 2026
Edit this page on GitHub
← Genocs.Saga Agent Reference
Genocs.Saga.Integrations.Redis Agent Reference →