Table of Contents

Interface IKafkaTransportBuilder

Namespace
Excalibur.Dispatch.Transport.Kafka
Assembly
Excalibur.Dispatch.Transport.Kafka.dll

Fluent builder interface for configuring Kafka transport.

public interface IKafkaTransportBuilder
Extension Methods

Examples

services.AddKafkaTransport("events", kafka =>
{
    kafka.BootstrapServers("localhost:9092")
         .UseSchemaRegistry(registry => registry.Url = "http://localhost:8081")
         .ConfigureProducer(producer => producer.Acks(KafkaAckLevel.All))
         .ConfigureConsumer(consumer => consumer.GroupId("my-group"))
         .MapTopic<OrderCreated>("orders-topic");
});

Remarks

This interface follows the Microsoft-style fluent builder pattern. It provides the single entry point for Kafka transport configuration.

All methods return this for method chaining, enabling a fluent configuration experience.

Methods

BootstrapServers(string)

Configures the Kafka bootstrap servers.

IKafkaTransportBuilder BootstrapServers(string servers)

Parameters

servers string

The bootstrap servers connection string (e.g., "localhost:9092").

Returns

IKafkaTransportBuilder

The builder for fluent chaining.

Examples

kafka.BootstrapServers("broker1:9092,broker2:9092,broker3:9092");

Remarks

Bootstrap servers are the initial connection points for the Kafka client. Multiple servers can be specified as a comma-separated list for high availability.

Exceptions

ArgumentException

Thrown when servers is null, empty, or whitespace.

ConfigureCloudEvents(Action<KafkaCloudEventOptions>)

Configures CloudEvents settings for the Kafka transport.

IKafkaTransportBuilder ConfigureCloudEvents(Action<KafkaCloudEventOptions> configure)

Parameters

configure Action<KafkaCloudEventOptions>

The action to configure CloudEvents options.

Returns

IKafkaTransportBuilder

The builder for fluent chaining.

Examples

kafka.ConfigureCloudEvents(ce =>
{
    ce.PartitioningStrategy = KafkaPartitioningStrategy.CorrelationId;
    ce.Producer.AcknowledgmentLevel = KafkaAckLevel.All;
    ce.Producer.EnableIdempotentProducer = true;
    ce.Producer.EnableTransactions = true;
    ce.Producer.TransactionalId = "orders-producer";
});

Remarks

Use this method to configure CloudEvents-specific settings such as:

  • Partitioning strategy (CorrelationId, EventType, etc.)
  • Default topic for CloudEvents
  • Acknowledgment levels and idempotency
  • Compression settings
  • Transaction support for exactly-once semantics

Exceptions

ArgumentNullException

Thrown when configure is null.

ConfigureConsumer(Action<IKafkaConsumerBuilder>)

Configures the Kafka consumer settings using a fluent builder.

IKafkaTransportBuilder ConfigureConsumer(Action<IKafkaConsumerBuilder> configure)

Parameters

configure Action<IKafkaConsumerBuilder>

The consumer configuration action.

Returns

IKafkaTransportBuilder

The builder for fluent chaining.

Examples

kafka.ConfigureConsumer(consumer =>
{
    consumer.GroupId("my-consumer-group")
            .AutoOffsetReset(KafkaOffsetReset.Earliest)
            .SessionTimeout(TimeSpan.FromSeconds(45));
});

Remarks

Use this method to configure consumer-specific settings such as group ID, offset reset behavior, and session management.

Exceptions

ArgumentNullException

Thrown when configure is null.

ConfigureProducer(Action<IKafkaProducerBuilder>)

Configures the Kafka producer settings using a fluent builder.

IKafkaTransportBuilder ConfigureProducer(Action<IKafkaProducerBuilder> configure)

Parameters

configure Action<IKafkaProducerBuilder>

The producer configuration action.

Returns

IKafkaTransportBuilder

The builder for fluent chaining.

Examples

kafka.ConfigureProducer(producer =>
{
    producer.Acks(KafkaAckLevel.All)
            .EnableIdempotence(true)
            .CompressionType(KafkaCompressionType.Snappy);
});

Remarks

Use this method to configure producer-specific settings such as acknowledgment level, compression, batching, and transactions.

Exceptions

ArgumentNullException

Thrown when configure is null.

MapTopic<TMessage>(string)

Maps a message type to a specific Kafka topic.

IKafkaTransportBuilder MapTopic<TMessage>(string topic) where TMessage : class

Parameters

topic string

The Kafka topic name for this message type.

Returns

IKafkaTransportBuilder

The builder for fluent chaining.

Type Parameters

TMessage

The message type to map.

Examples

kafka.MapTopic<OrderCreated>("orders-events")
     .MapTopic<PaymentReceived>("payment-events");

Remarks

When a mapping exists for a message type, the transport will publish that message to the specified topic instead of using the default topic derivation.

Exceptions

ArgumentException

Thrown when topic is null, empty, or whitespace.

RequireTls(bool)

Configures whether broker connections must be encrypted. Enabled by default.

IKafkaTransportBuilder RequireTls(bool require = true)

Parameters

require bool

true to refuse to build a Kafka client whose security protocol does not carry TLS; false to permit an unencrypted connection.

Returns

IKafkaTransportBuilder

The builder for fluent chaining.

Examples

// A local broker with no TLS listener.
kafka.BootstrapServers("localhost:9092").RequireTls(false);

Remarks

Passing false permits credentials and message payloads to travel in the clear. It exists for local brokers and test fixtures, not for anything holding real data.

UseConfluentSchemaRegistry(Action<IConfluentSchemaRegistryBuilder>)

Configures the transport to use Confluent Schema Registry with fluent builder configuration.

IKafkaTransportBuilder UseConfluentSchemaRegistry(Action<IConfluentSchemaRegistryBuilder> configure)

Parameters

configure Action<IConfluentSchemaRegistryBuilder>

The action to configure schema registry options using the fluent builder.

Returns

IKafkaTransportBuilder

The builder for fluent chaining.

Examples

kafka.UseConfluentSchemaRegistry(registry =>
{
    registry.SchemaRegistryUrl("http://localhost:8081")
            .SubjectNameStrategy(SubjectNameStrategy.TopicNameStrategy)
            .CompatibilityMode(CompatibilityMode.Backward)
            .AutoRegisterSchemas(true)
            .CacheSchemas(true)
            .CacheCapacity(1000);
});

Remarks

This method follows Microsoft-style fluent builder patterns and provides a discoverable API for Schema Registry configuration.

When schema registry is enabled:

  • Messages are serialized with a 5-byte Confluent wire format header
  • Schemas are automatically registered on first publish (if enabled)
  • Incoming messages are validated against registered schemas
  • Schema compatibility is enforced based on the configured mode

Exceptions

ArgumentNullException

Thrown when configure is null.

UseSchemaRegistry(Action<ConfluentSchemaRegistryOptions>?)

Configures the transport to use Confluent Schema Registry for schema validation.

IKafkaTransportBuilder UseSchemaRegistry(Action<ConfluentSchemaRegistryOptions>? configure = null)

Parameters

configure Action<ConfluentSchemaRegistryOptions>

Optional action to configure schema registry options.

Returns

IKafkaTransportBuilder

The builder for fluent chaining.

Examples

kafka.UseSchemaRegistry(registry =>
{
    registry.Url = "http://localhost:8081";
    registry.Schema.DefaultCompatibility = CompatibilityMode.Backward;
});

Remarks

When schema registry is enabled:

  • Schemas are automatically registered on first publish
  • Incoming messages are validated against registered schemas
  • Schema compatibility is enforced based on the configured mode

Note: Prefer UseConfluentSchemaRegistry(Action<IConfluentSchemaRegistryBuilder>) for new code. This method provides backward compatibility with options-based configuration.

UseSecurityProtocol(SecurityProtocol)

Configures the security protocol used for broker connections.

IKafkaTransportBuilder UseSecurityProtocol(SecurityProtocol protocol)

Parameters

protocol SecurityProtocol

The security protocol.

Returns

IKafkaTransportBuilder

The builder for fluent chaining.

Examples

kafka.BootstrapServers("broker:9093")
     .UseSecurityProtocol(SecurityProtocol.SaslSsl);

Remarks

Every Kafka client this transport builds -- producer, consumer, admin and dead-letter clients -- is configured with this protocol. A protocol that does not carry TLS is refused when the client is built unless RequireTls(bool) has been turned off.

Setting this and the raw security.protocol configuration key to different values is refused rather than resolved. Use one or the other.

WithTopicPrefix(string)

Sets a prefix to apply to automatically generated topic names.

IKafkaTransportBuilder WithTopicPrefix(string prefix)

Parameters

prefix string

The topic name prefix (e.g., "myapp-", "prod-").

Returns

IKafkaTransportBuilder

The builder for fluent chaining.

Examples

kafka.WithTopicPrefix("myapp-prod-");
// Messages of type OrderCreated would go to "myapp-prod-ordercreated"

Remarks

The prefix is applied to topic names that are automatically derived from message type names, helping to organize topics by application or environment.

Exceptions

ArgumentException

Thrown when prefix is null, empty, or whitespace.