Cratis Package

The Cratis NuGet package provides a simplified setup for building applications with Arc and Chronicle event sourcing. It combines Arc's application framework with Chronicle's event sourcing capabilities in a single, streamlined package.

What is the Cratis Package?

The Cratis package is a convenience package that bundles:

Arc Application Framework - CQRS patterns, validation, multi-tenancy, and more
Chronicle Event Sourcing - Event store, aggregates, projections, and event handling
Swagger/OpenAPI - Automatic API documentation generation

It's designed to get you up and running quickly with a complete event-sourced application stack without manually configuring each component.

Installation

Add the Cratis package to your ASP.NET Core project:

dotnet add package Cratis

Basic Setup

Configure Cratis in your Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Add Cratis with default configuration
builder.AddCratis();

var app = builder.Build();

// Use Cratis middleware and endpoints
app.UseCratis();

app.Run();

This minimal setup configures:

Arc's command and query infrastructure
Chronicle's event store and event handling
Swagger/OpenAPI documentation
Validation and model binding
Multi-tenancy support

Advanced Configuration

You can customize both Arc and Chronicle components using the optional configuration callbacks:

builder.AddCratis(
    configureArcOptions: options =>
    {
        // Configure Arc options
        options.UseControllerBasedRouting = true;
    },
    configureArcBuilder: arcBuilder =>
    {
        // Configure additional Arc features
        arcBuilder.WithMongoDB();
    },
    configureArcChronicleOptions: options =>
    {
        // Configure Chronicle options
        options.ClusterName = "my-cluster";
    },
    configureChronicleBuilder: chronicleBuilder =>
    {
        // Configure Chronicle features
    });

Adding MongoDB Support

By default, the Cratis package doesn't include MongoDB support. To use MongoDB with your application, add the MongoDB package separately:

dotnet add package Cratis.Applications.MongoDB

Then configure MongoDB using the WithMongoDB extension method:

builder.AddCratis(
    configureArcBuilder: arcBuilder =>
    {
        arcBuilder.WithMongoDB();
    });

MongoDB Configuration Options

You can customize MongoDB settings using the configuration callback:

builder.AddCratis(
    configureArcBuilder: arcBuilder =>
    {
        arcBuilder.WithMongoDB(
            configureOptions: options =>
            {
                options.Server = "mongodb://localhost:27017";
                options.Database = "my-database";
            });
    });

MongoDB Configuration from appsettings.json

Alternatively, configure MongoDB settings in appsettings.json:

{
  "MongoDB": {
    "Server": "mongodb://localhost:27017",
    "Database": "my-database"
  }
}

The WithMongoDB extension automatically reads these settings from the configuration section.

Custom Configuration Section Path

If your MongoDB settings are in a different configuration section:

arcBuilder.WithMongoDB(
    mongoDBConfigSectionPath: "MyApp:Database:MongoDB");

Adding Entity Framework Core Support

To use Entity Framework Core with your application, add the Entity Framework Core package:

dotnet add package Cratis.Applications.EntityFrameworkCore

Once added, you can define and configure your DbContext classes as you normally would in Entity Framework Core. Arc automatically discovers and configures registered DbContexts with enhanced features like:

Automatic multi-tenancy support
Integration with Arc's dependency injection
Streamlined configuration patterns

See the Entity Framework Core documentation for detailed configuration options and best practices.

Next Steps

Now that you have Cratis set up, you can:

Define Commands to handle user actions
Create Queries to retrieve data
Build Aggregates to model your domain
Configure MongoDB for read models and projections
Set up Multi-tenancy for your application

For more advanced scenarios, explore the individual Arc and Chronicle components in the documentation.

Table of Contents