Configuration Reference

This page provides a quick-reference index of all configuration options across Ratatoskr. Each table links to the feature page where the option is documented in detail.

Core

builder.Services.AddRatatoskr(bus =>
{
    // All configuration happens here
});

Channel Methods

Method	Intent	Details
`AddEventPublishChannel(name, ...)`	Publish events you own	Channels & Routing
`AddCommandPublishChannel(name, ...)`	Send commands to others	Channels & Routing
`AddEventConsumeChannel(name, ...)`	Subscribe to others' events	Channels & Routing
`AddCommandConsumeChannel(name, ...)`	Process commands you own	Channels & Routing

Message & Handler Registration

Method	Description	Details
`.Produces<T>()`	Register a message type on a publish channel	Channels & Routing
`.Consumes<T>(m => ...)`	Register a message type and handlers on a consume channel	Messages & Handlers
`.WithSerializer<TSerializer>()`	Use a serializer for a specific message type	Messages & Handlers
`.WithHandler<T>()`	Fire-and-forget handler (no persistence)	Messages & Handlers
`.WithHandler<T>("key")`	Inbox-managed handler with stable key	Inbox
`.AllowConsumeWithoutInbox()`	Explicit opt-out from optional consume-channel inbox requirement policy	Inbox

Attributes

Attribute	Target	Description	Details
`[RatatoskrMessage("type")]`	Class/Record	Sets the CloudEvents `type` and default routing key	Messages & Handlers
`[AsyncApiMessage(...)]`	Class/Record	Adds AsyncAPI documentation metadata	AsyncAPI

CloudEvents

bus.ConfigureCloudEvents(ce =>
{
    ce.DefaultSource = "/order-service";
    ce.ContentMode = CloudEventsContentMode.Binary;
});

Property	Default	Description	Details
`DefaultSource`	`"/"`	CloudEvents `source` URI	CloudEvents
`ContentMode`	`Binary`	Wire encoding mode (`Binary` or `Structured`)	CloudEvents

RabbitMQ Transport

bus.UseRabbitMq(c =>
{
    c.ConnectionString = new Uri("amqp://guest:guest@localhost:5672/");
    c.MaxInboundMessageSize = 1048576; // 1 MB limit
});

Global Options

Option	Default	Description	Details
`ConnectionString`	—	RabbitMQ connection URI	RabbitMQ
`UsePublisherConfirms`	`true`	Wait for publisher acks	RabbitMQ
`MaxInboundMessageSize`	none	Max body size in bytes before rejection	RabbitMQ

Channel Options

Option	Default	Description	Details
`WithTopicExchange()`	Topic	Pattern-based routing	RabbitMQ
`WithDirectExchange()`	—	Exact routing key match	RabbitMQ
`WithFanoutExchange()`	—	Broadcast to all queues	RabbitMQ
`WithQueueName(string)`	(required)	Queue to consume from	RabbitMQ
`WithPrefetch(ushort)`	`10`	Max unacknowledged messages	RabbitMQ
`WithQueueType(QueueType)`	`Quorum`	Queue implementation (Quorum/Classic)	RabbitMQ
`WithAutoAck(bool)`	`false`	Auto-acknowledge on delivery	RabbitMQ
`WithDurableQueue()`	(default)	Survives broker restarts	RabbitMQ
`WithTransientQueue()`	—	Deleted when the last consumer disconnects	RabbitMQ

Retry Options

Option	Default	Description	Details
`WithMaxRetries(int)`	`3`	Attempts before DLQ	RabbitMQ
`WithDelay(TimeSpan)`	`30s`	TTL on retry queue	RabbitMQ
`WithManaged(bool)`	`true`	Auto-provision retry/DLQ topology	RabbitMQ
`WithDeadLetterSuffix(string)`	`".dlq"`	DLQ name suffix	RabbitMQ
`WithRetrySuffix(string)`	`".retry"`	Retry queue name suffix	RabbitMQ

EF Core Durability

bus.AddEfCoreDurability<OrderDbContext>(d =>
{
    d.UseOutbox(outbox => { /* options */ });
    d.UseInbox(inbox => { /* options */ });
});

Durability builder (shared)

Option	Default	Description	Details
`WithMetricsPollingInterval(TimeSpan)`	`30s`	How often backlog gauge counts are refreshed from the database	Observability
`WithMetricsQueryTimeout(TimeSpan)`	`5s`	Per-`COUNT` query cancellation timeout for those refreshes	Observability

Outbox Options

Option	Default	Description	Details
`WithMaxRetries(int)`	`5`	Send attempts before poisoned	Outbox
`WithMaxRetryDelay(TimeSpan)`	`5 min`	Max backoff delay	Outbox
`WithPollingInterval(TimeSpan)`	`60s`	Idle polling interval	Outbox
`WithBatchSize(int)`	`100`	Messages per batch	Outbox
`WithStuckMessageThreshold(TimeSpan)`	`5 min`	Stuck detection timeout	Outbox
`WithSendTimeout(TimeSpan)`	none	Send operation timeout	Outbox
`WithMaxMessageSize(int)`	none	Max body size in bytes	Outbox
`WithRestartDelay(TimeSpan)`	`5s`	Processor restart delay	Outbox
`WithLockAcquireTimeout(TimeSpan)`	`60s`	Lock acquire timeout	Outbox
`WithLockName(string)`	`"OutboxProcessor_{DbContext}"`	Distributed lock name	Outbox
`WithRetention(TimeSpan)`	none	Auto-cleanup retention	Outbox
`WithCleanupInterval(TimeSpan)`	`1h`	Cleanup run interval	Outbox
`WithCleanupBatchSize(int)`	`10,000`	Cleanup batch size	Outbox
`WithCleanupLockName(string)`	`"OutboxCleanup_{DbContext}"`	Cleanup distributed lock name	Operations
`WithoutBackgroundProcessing()`	—	Disable background service (testing)	Testing

Inbox Options

Option	Default	Description	Details
`WithMaxRetries(int)`	`5`	Delivery attempts before poisoned	Inbox
`WithMaxRetryDelay(TimeSpan)`	`5 min`	Max backoff delay (with jitter)	Inbox
`WithPollingInterval(TimeSpan)`	`30s`	Idle polling interval	Inbox
`WithBatchSize(int)`	`100`	Handler statuses per batch	Inbox
`WithStuckMessageThreshold(TimeSpan)`	`5 min`	Stuck detection timeout	Inbox
`WithHandlerTimeout(TimeSpan)`	none	Handler execution timeout	Inbox
`WithRestartDelay(TimeSpan)`	`5s`	Processor restart delay	Inbox
`WithLockAcquireTimeout(TimeSpan)`	`60s`	Lock acquire timeout	Inbox
`WithLockName(string)`	`"InboxProcessor_{DbContext}"`	Distributed lock name	Inbox
`WithRetention(TimeSpan)`	none	Auto-cleanup retention	Inbox
`WithCleanupInterval(TimeSpan)`	`1h`	Cleanup run interval	Inbox
`WithCleanupBatchSize(int)`	`10,000`	Cleanup batch size	Inbox
`WithCleanupLockName(string)`	`"InboxCleanup_{DbContext}"`	Cleanup distributed lock name	Operations
`WithConsumeChannelInboxRequirement(ConsumeChannelInboxRequirement)`	`None`	Optional safeguard: warn/fail when consume channels omit `UseInbox()`	Inbox
`WithoutBackgroundProcessing()`	—	Disable background service (testing)	Testing

AsyncAPI

bus.ConfigureAsyncApi(api =>
{
    api.WithTitle("Order Processing API");
    api.WithVersion("1.0.0");
    api.WithDescription("Order processing messaging API");
});

Method	Description	Details
`WithTitle(string)`	API document title	AsyncAPI
`WithVersion(string)`	API version	AsyncAPI
`WithDescription(string)`	API description	AsyncAPI
`app.MapAsyncApi()`	Map the AsyncAPI JSON endpoint	AsyncAPI

OpenTelemetry

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource(RatatoskrDiagnostics.ActivitySourceName))
    .WithMetrics(m => m.AddMeter(RatatoskrDiagnostics.MeterName));

Constant	Value	Description	Details
`RatatoskrDiagnostics.ActivitySourceName`	`"Ratatoskr"`	Tracing activity source	Observability
`RatatoskrDiagnostics.MeterName`	`"Ratatoskr"`	Metrics meter	Observability

Testing

services.AddRatatoskrTesting();

Method	Description	Details
`AddRatatoskrTesting()`	Register the message tracker	Testing
`CreateTrackingSession()`	Create a trace-isolated test session	Testing
`TrackActivity()`	Start the action-based tracking API	Testing

Distributed Lock Provider

The lock provider is registered as IDistributedLockProvider in DI. See Operations for provider options (File, PostgreSQL, SQL Server, Redis).