Class ChronicleOptions

Namespace: Cratis.Chronicle

Assembly: Cratis.Chronicle.dll

Represents the settings for connecting to Chronicle.

public class ChronicleOptions

Inheritance: object

ChronicleOptions

Derived: ChronicleClientOptions

ChronicleClientOptions

Inherited Members: object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Extension Methods: MethodCalls.CallGenericMethod<TOut, T>(T, Expression<Func<T, Func<TOut>>>, params Type[])

MethodCalls.CallGenericMethod<TOut, T, T1>(T, Expression<Func<T, Func<T1, TOut>>>, T1, params Type[])

MethodCalls.CallGenericMethod<TOut, T, T1, T2>(T, Expression<Func<T, Func<T1, T2, TOut>>>, T1, T2, params Type[])

MethodCalls.CallGenericMethod<TOut, T, T1, T2, T3>(T, Expression<Func<T, Func<T1, T2, T3, TOut>>>, T1, T2, T3, params Type[])

ConverterExtensions.ConvertTo(object, Type)

ConceptExtensions.GetConceptValue(object)

ConceptExtensions.IsConcept(object)

JsonValueExtensions.ToJsonValue(object?)

ObservableExtensions.InvokeAndWrapWithSubject<TResult>(object, Func<CancellationToken, IObservable<TResult>>)

ObservableExtensions.InvokeAndWrapWithTransformSubject<TResult, TSource>(object, Func<CancellationToken, IObservable<TSource>>, Func<TSource, TResult>)

Remarks

Using the default constructor initializes the options with the development connection string (Development), which includes the default development client credentials. This is intended for local development and testing only.

Constructors

ChronicleOptions()

Initializes a new instance of the ChronicleOptions class.

public ChronicleOptions()

Remarks

This initializes the options with the development connection string (Development), which includes the default development client credentials.

ChronicleOptions(ChronicleConnectionString, JsonSerializerOptions?, ConcurrencyOptions?, bool, int)

Represents the settings for connecting to Chronicle.

public ChronicleOptions(ChronicleConnectionString connectionString, JsonSerializerOptions? jsonSerializerOptions = null, ConcurrencyOptions? concurrencyOptions = null, bool autoDiscoverAndRegister = true, int connectTimeout = 5)

Parameters

connectionString ChronicleConnectionString: ChronicleConnectionString to use.
jsonSerializerOptions JsonSerializerOptions: Optional JsonSerializerOptions to use. Will revert to defaults if not configured.
concurrencyOptions ConcurrencyOptions: Optional ConcurrencyOptions to use. Will revert to default if not configured.
autoDiscoverAndRegister bool: Optional disable automatic discovery of artifacts and registering these.
connectTimeout int: Optional timeout when connecting in seconds. Defaults to 5.

Remarks

Properties

ActivationId

Gets or sets the logical lifecycle identity shared by instances of one rollout. Required for lifecycle handlers unless ActivationScope is PerProcess.

public ActivationId? ActivationId { get; set; }

Property Value

ActivationId

ActivationScope

Gets or sets whether the host supplies a logical activation or explicitly opts into per-process lifecycle.

public ActivationScope ActivationScope { get; set; }

Property Value

ActivationScope

ArtifactIdentityDrift

Gets or sets how likely artifact renames or moves are handled before registration. Defaults to Warn. Fail escalates only Warning-level reactor and event type findings, not Information-level read model findings. Snapshot failures never prevent registration, even under Fail.

public ArtifactIdentityDriftPolicy ArtifactIdentityDrift { get; set; }

Property Value

ArtifactIdentityDriftPolicy

Authentication

Gets or sets the authentication configuration.

public Authentication Authentication { get; set; }

Property Value

Authentication

AutoDiscoverAndRegister

Gets a value indicating whether to automatically discover and register artifacts.

public bool AutoDiscoverAndRegister { get; set; }

Property Value

bool

ClaimsBasedNamespaceResolverClaimType

Gets or sets the claim type to use for claims-based namespace resolution. This is used by the ClaimsBasedNamespaceResolver when configured via the WithClaimsBasedNamespaceResolver extension method.

public string ClaimsBasedNamespaceResolverClaimType { get; set; }

Property Value

string

ConcurrencyOptions

Gets the ConcurrencyOptions to use for concurrency management.

public ConcurrencyOptions ConcurrencyOptions { get; set; }

Property Value

ConcurrencyOptions

ConnectTimeout

Gets the timeout when connecting in seconds.

public int ConnectTimeout { get; set; }

Property Value

int

ConnectionString

Gets the ChronicleConnectionString to use.

public ChronicleConnectionString ConnectionString { get; set; }

Property Value

ChronicleConnectionString

DefaultSinkTypeId

Gets or sets the default SinkTypeId used when registering projections and reducers. When not explicitly configured, defaults to MongoDB. Set to SQL to persist read models into a SQL database.

public SinkTypeId DefaultSinkTypeId { get; set; }

Property Value

SinkTypeId

EnableEventTypeGenerationValidation

Gets or sets a value indicating whether event type generation validation is enabled. When false (the default), the client asks the Kernel to bypass migration chain validation when registering event types at generation 2 or higher. Set to true to opt into strict migration chain validation.

public bool EnableEventTypeGenerationValidation { get; set; }

Property Value

bool

Remarks

The Kernel only honours this flag when running the development image. The production image always enforces validation unconditionally, regardless of the value sent by the client.

The default is false so that early-stage schema development works without any explicit configuration. Set to true to opt into strict migration chain validation on the development Kernel image.

EventGenerationDelivery

Gets or sets how client reactors, reducers, and typed materialized projections receive event generations. Defaults to Compatibility; Pinned requests kernel selection and release of the subscribed generation.

public EventGenerationDelivery EventGenerationDelivery { get; set; }

Property Value

EventGenerationDelivery

ExplicitArtifacts

Gets the ExplicitArtifacts - read models, projections and reactors registered with the client explicitly rather than found by discovery, for every event store the client creates.

public ExplicitArtifacts ExplicitArtifacts { get; }

Property Value

ExplicitArtifacts

Remarks

Register here while configuring the client - before it connects - so that every event store includes the registrations in its normal registration pass and in every re-registration after a reconnect. An event store that already exists is registered with directly, through its Projections, ReadModels and Reactors.

JsonSerializerOptions

Gets the JsonSerializerOptions to use.

public JsonSerializerOptions JsonSerializerOptions { get; set; }

Property Value

JsonSerializerOptions

LifecycleScope

Gets or sets the lifecycle delivery boundary. Application scope is the default.

public LifecycleScope LifecycleScope { get; set; }

Property Value

LifecycleScope

LoadBalancerStrategy

Gets or sets the ILoadBalancerStrategy to use when the connection string holds multiple servers. When not set, the strategy named by the connection string's loadBalancer option is used, defaulting to round-robin.

public ILoadBalancerStrategy? LoadBalancerStrategy { get; set; }

Property Value

ILoadBalancerStrategy

MaxReceiveMessageSize

Gets or sets the maximum receive message size in bytes for gRPC messages. Defaults to 100 MB.

public int? MaxReceiveMessageSize { get; set; }

Property Value

int?

MaxSendMessageSize

Gets or sets the maximum send message size in bytes for gRPC messages. Defaults to 100 MB.

public int? MaxSendMessageSize { get; set; }

Property Value

int?

ProgramIdentifier

Gets or sets the program identifier.

public string ProgramIdentifier { get; set; }

Property Value

string

Reactors

Gets or sets how reactors are run, such as how many partitions are handled at the same time.

public ReactorOptions Reactors { get; set; }

Property Value

ReactorOptions

Reducers

Gets or sets how reducers are run, such as how many partitions are handled at the same time.

public ReducerOptions Reducers { get; set; }

Property Value

ReducerOptions

RegistrationRetry

Gets or sets how registering the client's artifacts is retried when the kernel does not accept them.

public RegistrationRetryOptions RegistrationRetry { get; set; }

Property Value

RegistrationRetryOptions

SkipCompatibilityCheck

Gets or sets a value indicating whether to skip the server compatibility check on connect.

public bool SkipCompatibilityCheck { get; set; }

Property Value

bool

Remarks

The client asks the server, on every connect, whether it still serves the contract this client was built against, and refuses to connect when the server says no (see Source/Kernel/Compatibility). That comparison runs on the server, so it is only as current as the kernel build answering it — a kernel that has not been redeployed since a wire-compatibility defect was fixed still computes the old, incorrect verdict, and no client-side change can make it compute a different one.

Set this to true as a deliberate escape hatch for exactly that situation — a known-safe skew against a kernel that cannot be redeployed to fix the check itself. It is not a general-purpose override: turning it on hides every other incompatibility too, including a genuine one. The connection string's skipCompatibilityCheck=true option asks for the same thing; either input is enough, see Cratis.Chronicle.CompatibilityCheckPolicy.

SkipKeepAlive

Gets or sets a value indicating whether to skip the keep-alive handshake on connect.

public bool SkipKeepAlive { get; set; }

Property Value

bool

Remarks

The default Chronicle client opens a bidirectional keep-alive stream right after connect. A background watchdog measures the time since the last server ping and, if it exceeds five seconds, treats the channel as dead — disposes the underlying gRPC channel, raises Disconnected(), and asks the connection to reconnect. This is exactly what a long-lived client wants: liveness detection that survives transient network glitches, kernel restarts, and silo reactivation.

For short-lived, one-shot callers the watchdog is a hazard rather than a feature. A development-only kernel reset (IServer.ResetKernelState), a CLI that issues a single command, or any other client whose lifetime is a single RPC does not benefit from liveness detection and is actively harmed by it: a single RPC that takes longer than the five-second window (for example a SQL backend wipe that has to enumerate, connect to, and drop tables across every event store / namespace / read-model database) trips the watchdog mid-call, disposes the channel out from under the in-flight call, and surfaces as ObjectDisposedException on Grpc.Net.Client.GrpcChannel.

Set this to true when the client will issue at most a handful of RPCs before being disposed, or when the longest RPC the client will issue can exceed five seconds of server-side processing. With keep-alive skipped the lifecycle is marked connected immediately after the gRPC channel is established, the watchdog is never started, and the channel survives for the full lifetime of the client.

SoftwareCommit

Gets or sets the software commit SHA. Defaults to the commit SHA from the entry assembly's (your application's) AssemblyInformationalVersion metadata (the portion after the '+' separator). This is included in the root causation to track which commit of your application is running.

public string SoftwareCommit { get; set; }

Property Value

string

SoftwareVersion

Gets or sets the software version. Defaults to the version of the entry assembly (your application), extracted from the AssemblyInformationalVersion or AssemblyVersion attribute. This is included in the root causation to track which version of your application is running.

public string SoftwareVersion { get; set; }

Property Value

string

Tls

Gets or sets the TLS configuration.

public Tls Tls { get; set; }

Property Value

Tls

UnitOfWorkLifecyclePolicy

Gets or sets how units of work handle event staging after completion begins. Defaults to Compatibility for this major version. Strict will become the default in the next major version.

public UnitOfWorkLifecyclePolicy UnitOfWorkLifecyclePolicy { get; set; }

Property Value

UnitOfWorkLifecyclePolicy

Methods

FromConnectionString(ChronicleConnectionString)

Create a ChronicleOptions from a ChronicleConnectionString.

public static ChronicleOptions FromConnectionString(ChronicleConnectionString connectionString)

Parameters

connectionString ChronicleConnectionString: ChronicleConnectionString to create from.

Returns

ChronicleOptions: A new ChronicleOptions.

FromConnectionString(string)

Create a ChronicleOptions from a connection string.

public static ChronicleOptions FromConnectionString(string connectionString)

Parameters

connectionString string: Connection string to create from.

Returns

ChronicleOptions: A new ChronicleOptions.

FromDevelopmentConnectionString()

Create a ChronicleOptions from the development connection string.

public static ChronicleOptions FromDevelopmentConnectionString()

Returns

ChronicleOptions: A new ChronicleOptions configured for development.

Remarks

This is a convenience method for quickly creating options for development purposes. It uses the default development connection string which points to localhost with the default development client credentials. This is not intended for production use and should only be used for local development and testing. For production scenarios, it's recommended to explicitly configure the connection string and other options as needed.