Interface IKafkaTransportBuilder
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
serversstringThe 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
serversis null, empty, or whitespace.
ConfigureCloudEvents(Action<KafkaCloudEventOptions>)
Configures CloudEvents settings for the Kafka transport.
IKafkaTransportBuilder ConfigureCloudEvents(Action<KafkaCloudEventOptions> configure)
Parameters
configureAction<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
configureis null.
ConfigureConsumer(Action<IKafkaConsumerBuilder>)
Configures the Kafka consumer settings using a fluent builder.
IKafkaTransportBuilder ConfigureConsumer(Action<IKafkaConsumerBuilder> configure)
Parameters
configureAction<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
configureis null.
ConfigureProducer(Action<IKafkaProducerBuilder>)
Configures the Kafka producer settings using a fluent builder.
IKafkaTransportBuilder ConfigureProducer(Action<IKafkaProducerBuilder> configure)
Parameters
configureAction<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
configureis null.
MapTopic<TMessage>(string)
Maps a message type to a specific Kafka topic.
IKafkaTransportBuilder MapTopic<TMessage>(string topic) where TMessage : class
Parameters
topicstringThe Kafka topic name for this message type.
Returns
- IKafkaTransportBuilder
The builder for fluent chaining.
Type Parameters
TMessageThe 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
topicis null, empty, or whitespace.
RequireTls(bool)
Configures whether broker connections must be encrypted. Enabled by default.
IKafkaTransportBuilder RequireTls(bool require = true)
Parameters
requirebooltrue 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
configureAction<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
configureis null.
UseSchemaRegistry(Action<ConfluentSchemaRegistryOptions>?)
Configures the transport to use Confluent Schema Registry for schema validation.
IKafkaTransportBuilder UseSchemaRegistry(Action<ConfluentSchemaRegistryOptions>? configure = null)
Parameters
configureAction<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
protocolSecurityProtocolThe 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
prefixstringThe 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
prefixis null, empty, or whitespace.