Skip to content

Configuration reference

This page is a lookup reference for the public configuration surface. For worked examples, use Configure the EF Core store, Use MongoDB, Build projections, or Publish integration messages.

builder.Services.AddEventLoom(eventLoom => eventLoom
.UsePostgreSql(builder.Configuration.GetConnectionString("EventStore")!)
.UseSingleTenancy()
.AddAggregate<Order, Guid>(aggregate => aggregate
.ConstructWith(id => new Order(id))
.UseStream("order", id => id.ToString("D"))));
builder.Services.AddEventLoom(eventLoom => eventLoom
.UseMongoDb(
builder.Configuration.GetConnectionString("EventStore")!,
databaseName: "eventloom")
.UseSingleTenancy()
.AddAggregate<Order, Guid>(aggregate => aggregate
.ConstructWith(id => new Order(id))
.UseStream("order", id => id.ToString("D"))));

Local or single-process SQLite application

Section titled “Local or single-process SQLite application”
builder.Services.AddEventLoom(eventLoom => eventLoom
.UseSqlite("Data Source=eventloom.db")
.UseSingleTenancy()
.AddAggregate<Order, Guid>(aggregate => aggregate
.ConstructWith(id => new Order(id))
.UseStream("order", id => id.ToString("D"))));

Choose one provider per application.

Method Purpose
services.AddEventLoom() Starts fluent registration and returns an EventLoomBuilder.
services.AddEventLoom(configure) Runs configuration and validates it before returning the service collection.
AddAggregate<TAggregate, TId>(configure) Registers a repository, stream mapping, factory, and all events owned by the aggregate.
AddAggregateEvents<TAggregate>() Registers events owned by an aggregate without registering a repository.
AddUpcaster(upcaster) Registers one deterministic event-payload upcaster.
ConfigureEventSerialization(configure) Configures JSON serialization for persisted events.
UseStorage(capabilities, register) Extension point for custom storage providers. Applications normally use a provider package instead.
UseSingleTenancy(tenantId) Uses one stable tenant; defaults to default.
UseMultiTenancy<TAccessor>() Enables multi-tenancy and registers a scoped ITenantAccessor.
UseMultiTenancy() Enables multi-tenancy when the application registers ITenantAccessor itself.
ConfigureWorkers(configure) Configures asynchronous projection workers.
ConfigureSnapshotRetention(policy) Sets the default snapshot retention policy.
AddProjection(name, configure, version) Registers one named projection with one or more handlers.
AddOutboxPublisher<TPublisher>(configure) Enables transactional outbox messages and registers the publisher worker.
UseTimeProvider(provider) Replaces the system clock; useful for deterministic tests.

AddProjection(name, configure, version) is the preferred projection API. Its registration builder makes the durable projection name and version explicit and chooses Asynchronous, provider-specific Transactional, or Inline per handler.

Select exactly one storage provider.

Method Effect
UsePostgreSql(connectionString[, configure]) Configures PostgreSQL, enables schemas, and installs the PostgreSQL retry policy.
UsePostgreSql(connectionFactory[, configure]) Uses a scoped DbConnection; required when sharing a relational unit of work.
UseSqlite(connectionString[, configure]) Configures SQLite, initializes its bundled native dependency, and disables schemas.
UseSqlite(connectionFactory[, configure]) Uses a scoped SQLite DbConnection; required when sharing a relational unit of work.
UseMongoDb(connectionString, databaseName[, configure]) Configures MongoDB storage for one database and installs the MongoDB retry policy.
UseMongoDb(clientFactory, databaseName[, configure]) Uses an application-supplied IMongoClient.

Provider packages also add provider-specific APIs:

  • EF Core: ConfigureEntityFramework(...), ConfigureProjectionModel(...), IEfProjectionHandler<TEvent>, unitOfWork.EnlistAsync(...), and unitOfWork.DbTransaction
  • MongoDB: IMongoProjectionHandler<TEvent>, MongoSessionAccessor, and unitOfWork.Session

Use ConfigureEntityFramework(...) from EventLoom.EntityFrameworkCore.

Property Default Rules and guidance
Schema eventloom PostgreSQL schema name. Keep stable after data exists. Ignored by SQLite.
TablePrefix eventloom_ Prefix for every EventLoom table. Keep stable after storage is created.

Schema support is provider-owned: PostgreSQL enables it, SQLite disables it.

Pass these options to UseMongoDb(..., configure).

Property Default Rules and guidance
CollectionPrefix eventloom_ Prefix for every EventLoom collection. Keep stable after data exists.
TransactionTimeout 30 seconds Must be positive. Sets the maximum MongoDB transaction commit time EventLoom requests.
RegisterStandardGuidSerializer true Best-effort process-wide registration of GuidSerializer(GuidRepresentation.Standard) so application documents can hold Guid values. Set false when the application registers its own Guid serializer.
Property Default Rules and guidance
Converters Empty Applied in registration order. Keep each converter compatible with every persisted payload it handles.
PropertyNamingPolicy CamelCase Treat as persisted payload compatibility.
PropertyNameCaseInsensitive false Strict matching exposes payload drift.
NumberHandling Strict Do not loosen without a deliberate stored-data compatibility decision.
ReferenceHandler null Events should normally be acyclic; reference metadata changes the payload contract.

ConfigureWorkers applies only to asynchronous projection workers.

Property Default Validation
InstanceId Generated process identity Nonempty and unique for each active process.
PollInterval 1 second Positive.
BatchSize 100 1 through 10,000.
LeaseDuration 30 seconds Positive and longer than LeaseRenewalInterval.
LeaseRenewalInterval 10 seconds Positive and shorter than LeaseDuration.
MaxRetryAttempts 5 0 through 100.

Pass these options to AddOutboxPublisher. They do not inherit ConfigureWorkers settings.

Property Default Validation
InstanceId Generated process identity Nonempty and unique for each active process.
PollInterval 1 second Positive.
BatchSize 100 1 through 10,000.
LeaseDuration 30 seconds Positive and longer than LeaseRenewalInterval.
LeaseRenewalInterval 10 seconds Positive and shorter than LeaseDuration.
MaxRetryAttempts 5 0 through 100.
SuccessfulDeliveryRetention TimeSpan.Zero Non-negative. Zero deletes a successfully delivered message and its attempts immediately.

If a projection or outbox worker iteration fails outside per-message delivery (for example tenant discovery, a checkpoint read, or lease acquisition throws because the store is unreachable), the worker logs a warning with the exception type only and keeps running. It waits PollInterval after the first consecutive failure and doubles the wait for each further failure, up to 30 seconds (or PollInterval when that is longer). The first successful iteration resets the backoff. Failures never stop the host or end the worker silently.

Declare an immutable snapshot DTO as IAggregateSnapshot<TSnapshot, TAggregate>, implement ISnapshotable<TSnapshot> on the aggregate, then call UseSnapshots<TSnapshot>(...) or UseSnapshots<TSnapshot>() in the aggregate registration. The typed builder accepts:

Method Effect
Every(interval) Captures every positive number of events.
UsePolicy(policy) Uses custom snapshot cadence.
KeepLatest(count) Retains a positive number of recent snapshots.
UseRetention(policy) Uses custom retention.
UseUpcasters(upcasters) Registers deterministic migrations for earlier snapshot schemas.
UseInvalidator(invalidator) Removes an unusable snapshot after EventLoom safely falls back to full replay.

The default capture cadence is every 100 events. The default retention policy keeps the latest snapshot for each tenant and aggregate stream.

Resolve IStorageSchema when you need provider-neutral bootstrap or validation:

Method Effect
EnsureCreatedAsync() Creates the provider’s storage objects when they do not already exist. Never migrates existing data.
ValidateAsync() Returns CanConnect, MissingCount, IncompatibleCount, and IsCompatible.

Use InitializeEventLoomDevelopmentDatabaseAsync() only for development bootstrap in ASP.NET Core applications.