Franz.Common.Messaging.Kafka 2.3.1

Franz.Common.Messaging.Kafka

Messaging and distributed integration for the Franz.Common framework on .NET 10.

Overview

The Franz.Common.Messaging.Kafka package provides messaging and distributed integration within Franz.Common. It is designed to compose with the rest of the framework rather than imposing unrelated infrastructure choices on every application.

Installation

dotnet add package Franz.Common.Messaging.Kafka

Design principles

• Explicit composition: register only the capabilities the application needs.
• Clear boundaries: keep domain and application contracts independent from provider-specific infrastructure where the package's role permits it.
• Predictable behavior: make configuration, failure modes, and lifecycle ownership visible rather than relying on hidden conventions.
• Operational readiness: validate security, resilience, diagnostics, and compatibility for the actual deployment environment.

Usage and configuration

Follow the package-specific setup, configuration, and code examples below. Only configure external services when this package requires them, and keep secrets outside source control.

Package-specific guide

A Kafka transport integration for the Franz Framework, designed to provide clean, deterministic, and production-grade interaction with Kafka topics, producers, and consumers.

This package focuses exclusively on Kafka transport concerns: configuration, producers, consumers, serialization, and transactions.

🧱 Hosting, background execution, and listeners are intentionally not handled here. They live in Franz.Common.Messaging.Hosting.Kafka.

✨ Features

Kafka Transport & Configuration

• Centralized Kafka configuration via MessagingOptions
• ConnectionProvider and ConnectionFactoryProvider for managing Kafka connections
• Deterministic, DI-friendly Kafka setup

Kafka Producers

• MessagingPublisher for publishing integration events
• MessagingSender for point-to-point messaging
• Automatic topic resolution and naming strategies

Kafka Consumers

• Native usage of Confluent.Kafka.IConsumer<string, string>
• IKafkaConsumerFactory as the single authority for consumer creation
• Correct lifetime management aligned with Kafka consumer group semantics

Modeling

• KafkaModel and ModelProvider for Kafka-based domain modeling
• Strong separation between messaging models and business logic

Serialization

• IMessageDeserializer
• JsonMessageDeserializer
• Deterministic JSON serialization using Franz messaging contracts

Transactions

• MessagingTransaction for Kafka-backed transactional workflows

Utilities

• ExchangeNamer and TopicNamer for consistent topic naming
• Messaging helpers shared across Franz transports

Dependency Injection

• Fluent ServiceCollectionExtensions for Kafka transport registration
• No accidental hosting or background execution side effects

🧭 Architectural Scope

This package is transport-only.

This separation ensures:

• Testability with Testcontainers
• Clean CI/CD pipelines
• No hidden threads or background services
• Reuse in CLI tools, workers, APIs, and serverless contexts

📦 Dependencies

This package depends on:

• Confluent.Kafka (2.3.0)
  Core Kafka client implementation

• Franz.Common.Messaging
  Core messaging abstractions and contracts

• Franz.Common.Annotations
  Messaging and modeling annotations

⚠️ Hosting integration is intentionally excluded. Use Franz.Common.Messaging.Hosting.Kafka for background listeners.

📥 Installation

From NuGet

dotnet add package Franz.Common.Messaging.Kafka

🚀 Usage

1️⃣ Register Kafka Transport

using Franz.Common.Messaging.Kafka.Extensions;

public void ConfigureServices(IServiceCollection services)
{
    services.AddKafkaMessaging(configuration);
}

This registers:

• Kafka producers
• Kafka senders
• Kafka consumers (transport only)

No hosted services are started.

2️⃣ Publish Messages

public class OrderPublisher
{
    private readonly IMessagingPublisher _publisher;

    public OrderPublisher(IMessagingPublisher publisher)
    {
        _publisher = publisher;
    }

    public async Task PublishAsync(OrderCreatedEvent evt)
    {
        await _publisher.PublishAsync(evt);
    }
}

3️⃣ Send Messages

public class PaymentSender
{
    private readonly IMessagingSender _sender;

    public PaymentSender(IMessagingSender sender)
    {
        _sender = sender;
    }

    public async Task SendAsync(PaymentCommand command)
    {
        await _sender.SendAsync(command);
    }
}

4️⃣ Kafka Consumers (Important)

Franz does not re-abstract Kafka consumers.

Consumers are provided directly by Confluent:

IConsumer<string, string>

They are:

• Created by IKafkaConsumerFactory
• Registered as long-lived singletons
• Fully compatible with Confluent.Kafka tooling and documentation

This avoids:

• Interface drift
• Partial re-implementations
• Subtle incompatibilities during upgrades

🧪 Testing & CI

This design is fully compatible with:

• Testcontainers (Kafka)
• Azure DevOps pipelines
• Docker-based integration tests
• Local developer environments

Because:

• No background services auto-start
• No implicit threads are created
• Kafka consumers are explicit and controlled

🔗 Integration with the Franz Framework

This package integrates with:

• Franz.Common.Messaging
• Franz.Common.Messaging.Hosting.Kafka (optional, for background execution)
• Franz.Common.Mediator
• Franz.Common.EntityFramework
• Franz.Common.Business

Kafka is treated as a transport, not an execution model.

🧾 Versioning & Changelog

Current Version: v2.3.0

Version 1.7.01

• 🧱 Corrected transport vs hosting separation
• 🔌 Removed Kafka consumer re-abstraction
• 🏭 Centralized consumer creation via IKafkaConsumerFactory
• ♻️ Fixed DI lifetimes for Kafka consumers
• 🧩 Clean separation between messaging and hosting layers
• 🧪 Improved Testcontainers and CI reliability

v2.0.2 – Internal Modernization

• Messaging and infrastructure refactored for async, thread-safety, and modern .NET 10 patterns.
• Full granular control of KafkaMessagingOptions.
• All APIs remain fully backward compatible.
• Tests, listeners, and pipeline components modernized.

2.0.7 – Kafka Registration now handles per Event registration automatically, no need to specify each event type manually.

📄 License

MIT License See the LICENSE file for details.

🧠 Final Note

This package intentionally mirrors enterprise messaging frameworks (MassTransit, NServiceBus, Brighter) by enforcing:

Transport ≠ Hosting

That separation is what makes Franz:

• Predictable
• Testable
• Scalable
• Production-safe

Dependency maintenance — October 2026

This project's dependency references were reviewed and updated as part of the repository-wide .NET 10 maintenance pass. The intended target framework and public API remain unchanged. Verify the resolved direct and transitive dependency graph through the repository's dependency validation workflow before publishing. See the central dependency upgrade record.