Genocs.Persistence.MongoDB

Genocs.Persistence.MongoDB — 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.Persistence.MongoDB provides MongoDB connectivity and repository wiring for Genocs services. It registers IMongoClient, IMongoDatabase, a generic IMongoRepository<TEntity>, session factory support, and optional collection seeding — all from a single mongoDb configuration section.

Quick Facts #

Install #

dotnet add package Genocs.Persistence.MongoDB

Minimal Integration Recipe (Program.cs) #

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

var builder = WebApplication.CreateBuilder(args);

IGenocsBuilder gnxBuilder = builder.AddGenocs();

gnxBuilder
    .AddMongoWithRegistration()
    .Build();

var app = builder.Build();
app.Run();

Configuration #

Use the mongoDb section in appsettings.json.

{
  "mongoDb": {
    "connectionString": "mongodb://localhost:27017",
    "database": "genocs_orders",
    "enableTracing": true,
    "seed": false,
    "setRandomDatabaseSuffix": false
  }
}

The option class includes validation semantics through MongoOptions.IsValid(...): registration is skipped when connectionString or database is empty.

Decision Matrix For Agents #

Behavior Notes / Constraints #

• AddMongo skips registration silently when the mongoDb section is absent or the connection string and database name are empty.
• BSON conventions (camelCase field names, string enums, Decimal128, CSharpLegacy GUIDs) are applied globally once per process.
• AddMongoWithRegistration registers IMongoRepository<T> with scoped lifetime; prefer scoped consumers.
• MongoDB connectivity is not verified at startup; connection errors surface on the first operation.
• Seeding runs through IMongoSeeder at initialization time only when seed: true is set.

Public Capability Map #

Dependencies #

• Genocs.Core
• MongoDB.Driver
• MongoDB.Driver.Core.Extensions.DiagnosticSources

Troubleshooting #

1. Repository services cannot be resolved from DI. Fix: Use AddMongoWithRegistration() to register the generic IMongoRepository<T>, or call AddMongoRepository<TEntity, TKey>() for typed collection mappings explicitly before Build().
2. Application fails to connect to MongoDB outside local development. Fix: Validate mongoDb.connectionString, ensure credentials and TLS settings are correct, and confirm that network and firewall rules permit the connection.
3. Seed data does not execute during startup. Fix: Set seed: true in the mongoDb configuration section and ensure a custom IMongoSeeder implementation is registered, or that the default seeder initialization flow is not suppressed.