ChronicleOptions Reference

ChronicleOptions is the root configuration class for all Chronicle .NET clients. All properties can be set in code via the configureOptions callback on AddCratisChronicle, and most can be bound directly from appsettings.json under the Cratis:Chronicle section.

There are three options classes that form an inheritance chain, each adding settings relevant to its hosting context:

Class	Used by	Adds
`ChronicleOptions`	All clients	Connection, serialization, timeouts, TLS, auth
`ChronicleClientOptions`	Worker services, console apps	Event store name, namespace resolver type
`ChronicleAspNetCoreOptions`	ASP.NET Core apps	HTTP header–based namespace resolution

appsettings.json

All bindable settings live under Cratis:Chronicle:

{
  "Cratis": {
    "Chronicle": {
      "ConnectionString": "chronicle://localhost:35000",
      "EventStore": "my-store",
      "EnableEventTypeGenerationValidation": false,
      "ConnectTimeout": 5,
      "AutoDiscoverAndRegister": true,
      "MaxReceiveMessageSize": 104857600,
      "MaxSendMessageSize": 104857600,
      "ManagementPort": 8080,
      "ProgramIdentifier": "my-app",
      "ClaimsBasedNamespaceResolverClaimType": "tenant_id",
      "Tls": {
        "CertificatePath": "/certs/client.pfx",
        "CertificatePassword": "secret"
      },
      "Authentication": {
        "Authority": "https://login.example.com"
      }
    }
  }
}

ChronicleOptions properties

EnableEventTypeGenerationValidation

Asks the Kernel to enforce strict migration chain validation when registering event types at generation 2 or higher. The value is forwarded as part of the registration request.


Type	`bool`
Default	`false`

Image restriction: This flag is only honoured by the development image of the Kernel. The production image always ignores it and validates unconditionally, regardless of what the client sends. This makes it impossible to accidentally skip migration chain validation in production even if the client has this flag set to false.

To opt in to strict validation during development (recommended once your event schemas are stable), set the flag to true:

builder.AddCratisChronicle(configureOptions: options =>
{
    options.EnableEventTypeGenerationValidation = true;
});

In appsettings.json: "EnableEventTypeGenerationValidation": true.

See Generation Validation for the full ruleset.

ConnectionString

The gRPC endpoint for Chronicle Server.


Type	`ChronicleConnectionString`
Default	Development connection string (`chronicle://localhost:35000` with default dev credentials)

options.ConnectionString = "chronicle://myserver:35000";

In appsettings.json: "ConnectionString": "chronicle://myserver:35000".

ConnectTimeout

Timeout in seconds when establishing a connection to Chronicle Server.


Type	`int`
Default	`5`

AutoDiscoverAndRegister

Controls whether Chronicle automatically discovers event types, projections, reactors, reducers, and other artifacts from loaded assemblies on startup.


Type	`bool`
Default	`true`

Set to false when using a custom IClientArtifactsProvider or when you want full manual control over what gets registered.

MaxReceiveMessageSize / MaxSendMessageSize

Maximum gRPC message sizes in bytes. See gRPC Message Size for detailed guidance.


Type	`int?`
Default	`104857600` (100 MB)

ManagementPort

Port used for the Management API and the well-known certificate endpoint.


Type	`int`
Default	`8080`

ProgramIdentifier

A human-readable identifier for the running application. Included in root causation metadata to identify which program appended an event.


Type	`string`
Default	`"[N/A]"`

SoftwareVersion

The software version of the entry assembly, extracted from AssemblyInformationalVersion or AssemblyVersion. Included in root causation to track which build produced an event.


Type	`string`
Default	Resolved from the entry assembly at startup

SoftwareCommit

The commit SHA of the entry assembly, extracted from the +commit part of AssemblyInformationalVersion. Included in root causation to track which commit produced an event.


Type	`string`
Default	Resolved from the entry assembly at startup

ClaimsBasedNamespaceResolverClaimType

The JWT claim type used by ClaimsBasedNamespaceResolver when namespace resolution is configured via WithClaimsBasedNamespaceResolver.


Type	`string`
Default	`"tenant_id"`

Tls

TLS certificate settings for the gRPC connection. TLS is active when both CertificatePath and CertificatePassword are set. See TLS for full details.


Type	`Tls`
Default	TLS disabled (no certificate configured)

Nested property	Type	Description
`CertificatePath`	`string?`	Path to a PFX certificate file
`CertificatePassword`	`string?`	Password for the certificate file

Authentication

OAuth/OIDC authority configuration. When Authority is not set, the Chronicle internal OAuth authority is used.


Type	`Authentication`
Default	Internal authority

Nested property	Type	Description
`Authority`	`string?`	OAuth/OIDC authority URL

ChronicleClientOptions properties

ChronicleClientOptions extends ChronicleOptions and is used by worker services, console apps, and other non-web hosts via IHostApplicationBuilder.AddCratisChronicle.

EventStore

The name of the event store the client connects to. Required.


Type	`EventStoreName`
Default	(none — must be set)

{ "Cratis": { "Chronicle": { "EventStore": "my-store" } } }

EventStoreNamespaceResolverType

The Type of the IEventStoreNamespaceResolver to use for resolving the event store namespace. When null, defaults to DefaultEventStoreNamespaceResolver at runtime, which always returns the default namespace.


Type	`Type?`
Default	`null` → `DefaultEventStoreNamespaceResolver`

This is a structural dependency — it resolves a type reference and cannot be meaningfully set from appsettings.json. Set it in code via the configureOptions callback or via IChronicleBuilder.

ChronicleAspNetCoreOptions properties

ChronicleAspNetCoreOptions extends ChronicleClientOptions and is used by ASP.NET Core applications via WebApplicationBuilder.AddCratisChronicle. It defaults EventStoreNamespaceResolverType to HttpHeaderEventStoreNamespaceResolver.

NamespaceHttpHeader

The HTTP request header used to resolve the event store namespace on a per-request basis.


Type	`string`
Default	`"x-cratis-tenant-id"`

{ "Cratis": { "Chronicle": { "NamespaceHttpHeader": "x-my-tenant" } } }

Table of Contents