Genocs.Persistence.MongoDB Agent Reference

This document is optimized for AI-assisted development sessions.

Genocs.Persistence.MongoDB Agent Reference

Purpose

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

  • What Genocs.Persistence.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.Persistence.MongoDB
Project filesrc/Genocs.Persistence.MongoDB/Genocs.Persistence.MongoDB.csproj
Target frameworksnet10.0, net9.0, net8.0
Primary roleMongoDB persistence integration with repository pattern support for Genocs applications
Core themesAddMongo and AddMongoWithRegistration extensions, repository abstractions and implementations, database/session providers, convention registration, paging utilities, optional seeding

Use This Package When

  • Registering MongoDB connectivity in a Genocs service.
  • Using generic repository abstractions backed by MongoDB collections.
  • Enabling convention-based BSON serialization defaults.
  • Running one-time database seeding during initialization.
  • Building paged query flows over Mongo IQueryable sources.

Do Not Assume

  • AddMongo returns early and registers nothing when the configured section does not exist.
  • Mongo registration is skipped when MongoOptions validation fails.
  • AddMongoWithRegistration only auto-registers IMongoRepository<> and does not scan custom repository types.

High-Value Entry Points

Service registration extensions

Core configuration contracts

Repository abstractions and implementations

Database access and session lifecycle

Initialization and conventions

Query pagination helpers

Decision Matrix For Agents

GoalPreferred APINotes
Register Mongo support from configurationAddMongo(builder, sectionName)Uses mongoDb section by default and validates options before DI setup
Register Mongo support from explicit valuesAddMongo(builder, MongoOptions options)Useful for tests or dynamic runtime options
Enable default repository registrationAddMongoWithRegistrationAdds scoped IMongoRepository<> to MongoRepository<>
Register custom repository implementationsRegisterMongoRepositories(assembly, lifetime)Scans dependencies for classes assignable to IMongoRepository<>
Add repository by explicit collection nameAddMongoRepository<TEntity, TKey>(collectionName)Registers IMongoBaseRepository<TEntity, TKey> with provided collection
Get database and client from DIIMongoDatabaseProviderProvides both IMongoClient and IMongoDatabase
Create Mongo session for transactionsIMongoSessionFactory.CreateAsyncStarts a client session handle via MongoClient
Execute paged queriesPagination.PaginateAsyncApplies page/result defaults and optional orderBy/sortOrder

Minimal Integration Recipe

Install 

dotnet add package Genocs.Persistence.MongoDB

Setup in Program.cs 

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

var builder = WebApplication.CreateBuilder(args);

IGenocsBuilder gnxBuilder = builder.AddGenocs();

gnxBuilder.AddMongoWithRegistration();

gnxBuilder.Build();

var app = builder.Build();

app.Run();

Behavior Notes That Affect Agent Decisions

  • Conventions are registered once per process through the static _conventionsRegistered flag.
  • AddMongo may append a GUID suffix to the database name when SetRandomDatabaseSuffix is true.
  • IMongoInitializer initialization runs once due to static interlocked guard and optionally triggers seeding.
  • EnableTracing configures DiagnosticsActivityEventSubscriber on MongoClientSettings.
  • Pagination defaults page and resultsPerPage to 1 and 10 when invalid values are provided.
  • Pagination.PaginateAsync returns PagedResult.Empty when the query source has no records.

Source-Accurate Capability Map

Mongo service wiring

  • Binds mongoDb configuration into MongoOptions.
  • Validates required options before registering Mongo client/database services.
  • Registers seeder, initializer, session factory, and database provider abstractions.
  • Supports optional conventions and repository registration extension paths.

Files:

Repository API surface

  • Defines generic repository contracts for querying, paging, add/update, and existence checks.
  • Provides ObjectId-specialized repository abstractions for Mongo entity types.
  • Includes two repository implementation styles: collection-name constructor and provider-based repository.
  • Resolves collection name by TableMappingAttribute when available, otherwise by entity type name.

Files:

Initialization and seeding lifecycle

  • Defines initialization contract compatible with Genocs initializer pipeline.
  • Executes database seed only when options.Seed is enabled.
  • Provides default seed strategy that exits early when collections already exist.

Files:

Database/session providers and option models

  • Exposes direct IMongoClient and IMongoDatabase access via provider abstraction.
  • Creates client settings from connection string and optional tracing instrumentation.
  • Exposes session factory abstraction for transaction-capable workflows.
  • Provides configuration objects for runtime Mongo and encryption settings.

Files:

Query pagination utilities

  • Converts IPagedQuery into ordered and limited Mongo IQueryable execution.
  • Supports dynamic sort property resolution through expression generation.
  • Computes total pages and returns typed paged result payloads.

Files:

Dependencies

From src/Genocs.Persistence.MongoDB/Genocs.Persistence.MongoDB.csproj:

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