Skip to content
Cratis Cratis Cratis

Getting Started

MongoDB integration in Cratis Applications is designed to be simple to set up while providing powerful defaults that work out of the box.

Basic Setup

Section titled “Basic Setup”

The simplest way to add MongoDB support to your application is through the configuration extension methods provided for WebApplicationBuilder or HostBuilder.

With WebApplicationBuilder

Section titled “With WebApplicationBuilder”
var builder = WebApplication.CreateBuilder(args);
builder.AddCratisArc();


builder.UseCratisMongoDB();


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

With HostBuilder

Section titled “With HostBuilder”
var host = Host.CreateDefaultBuilder(args)
    .AddCratisArc()
    .UseCratisMongoDB()
    .Build();

What Gets Configured

Section titled “What Gets Configured”

When you call UseCratisMongoDB(), the following components are automatically configured:

Default Serializers

Section titled “Default Serializers”
  • DateTimeOffset: Proper handling of timezone information
  • DateOnly: .NET 6+ date-only types
  • TimeOnly: .NET 6+ time-only types
  • System.Type: Serialization of .NET type information
  • Guid: Configured to use the standard .NET representation instead of MongoDB’s legacy format
  • Cratis Concepts: Automatic serialization for all types implementing ConceptAs<T>

Convention Packs

Section titled “Convention Packs”
  • Naming Policy Convention: Applies your configured naming policy to all properties
  • Ignore Extra Elements: Ignores unknown properties during deserialization

Automatic Discovery

Section titled “Automatic Discovery”
  • Class Maps: All implementations of IBsonClassMapFor<T> are automatically discovered and registered
  • Convention Pack Providers: All implementations of ICanProvideMongoDBConventionPacks are discovered
  • Convention Pack Filters: All implementations of ICanFilterMongoDBConventionPacksForType are discovered

Configuration Options

Section titled “Configuration Options”

You can customize the MongoDB setup by providing configuration options:

builder.UseCratisMongoDB(configureMongoDB: mongoBuilder =>
{
    mongoBuilder
        .WithCamelCaseNamingPolicy()
        .WithServerResolver<MyCustomServerResolver>()
        .WithDatabaseResolver<MyCustomDatabaseNameResolver>();
});

Connection Configuration

Section titled “Connection Configuration”

The framework uses resolver patterns for determining connection details:

Server Connection

Section titled “Server Connection”

Implement IMongoServerResolver to provide connection string logic:

public class MyServerResolver : IMongoServerResolver
{
    public MongoUrl Resolve()
    {
        return new MongoUrl("mongodb://localhost:27017");
    }
}

Database Name

Section titled “Database Name”

Implement IMongoDatabaseNameResolver to provide database naming logic:

public class MyDatabaseNameResolver : IMongoDatabaseNameResolver
{
    public string Resolve()
    {
        return "MyApplicationDatabase";
    }
}

Sane Defaults

Section titled “Sane Defaults”

Guid Representation

Section titled “Guid Representation”

One of the most common pain points when working with MongoDB and .NET is Guid serialization. By default, MongoDB stores Guids using a legacy binary format that can cause issues. Cratis Applications configures Guids to use the standard .NET representation, making them more predictable and interoperable.

Error Handling

Section titled “Error Handling”

The framework includes sensible error handling for common configuration issues:

  • Missing server resolver configuration
  • Missing database name resolver configuration
  • Missing naming policy configuration

These will throw descriptive exceptions with guidance on how to fix the configuration.

Next Steps

Section titled “Next Steps”