LinKit.Messaging.Kafka 1.5.1

dotnet add package LinKit.Messaging.Kafka --version 1.5.1
                    
NuGet\Install-Package LinKit.Messaging.Kafka -Version 1.5.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="LinKit.Messaging.Kafka" Version="1.5.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="LinKit.Messaging.Kafka" Version="1.5.1" />
                    
Directory.Packages.props
<PackageReference Include="LinKit.Messaging.Kafka" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add LinKit.Messaging.Kafka --version 1.5.1
                    
#r "nuget: LinKit.Messaging.Kafka, 1.5.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package LinKit.Messaging.Kafka@1.5.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=LinKit.Messaging.Kafka&version=1.5.1
                    
Install as a Cake Addin
#tool nuget:?package=LinKit.Messaging.Kafka&version=1.5.1
                    
Install as a Cake Tool

LinKit.Messaging.Kafka

This package provides the Apache Kafka broker adapter for the messaging abstractions in LinKit.Core. Core source generation wires supported message declarations and consumers to this broker adapter.

Prerequisites

  • You must have LinKit.Core installed.
  • You need access to a running Kafka cluster.
  • This package depends on the native librdkafka library via Confluent.Kafka. Ensure it is compatible with your target deployment environment, especially for AOT scenarios.

The Confluent.Kafka dependency uses native librdkafka components. Validate the package/runtime assets for each deployment OS and architecture. Source generation in LinKit does not itself certify the native Kafka client as Native AOT compatible.

Installation

dotnet add package LinKit.Messaging.Kafka

How to Use

1. Configure appsettings.json

Add a configuration section for your Kafka connection. The default section name is "Kafka".

{
  "Kafka": {
    "BootstrapServers": "localhost:9092",
    "GroupId": "my-application-consumer-group"
  }
}

GroupId is required for consumer groups. MaxProcessingAttempts controls handler retries before publishing a failed record to <source-topic>.dlq; 0 retries indefinitely and can block progress on that partition. The destination topic must be provisioned/configured according to your Kafka cluster policy.

AddLinKitKafka registers an IValidateOptions<KafkaOptions>, so configuration problems surface the first time IOptions<KafkaOptions>.Value is resolved (for a hosted consumer, during startup) as an OptionsValidationException. Validated: BootstrapServers and GroupId must not be blank, BatchSize must be positive, LingerMs and MaxProcessingAttempts must not be negative, and DeadLetterTopicSuffix must not be null.

Configuration reference
Property Default Purpose
BootstrapServers localhost:9092 Comma separated host:port list used to bootstrap cluster metadata.
GroupId linkit-consumer-group Consumer group that owns the committed offsets; each group reads the topic independently.
LingerMs 5 Time to wait for more records before a batch is sent; higher values trade latency for throughput.
BatchSize 65536 Maximum bytes batched per partition before a send is forced.
CompressionType None Compression codec applied to produced batches.
AutoOffsetReset Earliest Where to start reading when the group has no committed offset.
EnableAutoCommit false Retained for configuration compatibility; LinKit disables broker auto-commit so offsets are committed after the handler succeeds.
MaxProcessingAttempts 5 Handler attempts per record before it is dead-lettered; 0 retries forever and can block the partition.
DeadLetterTopicSuffix .dlq Appended to the source topic name to build the dead-letter topic; use an empty string to disable the suffix.

LinKit commits Kafka offsets only after the generated message handler completes successfully. Failed handler calls are sought back to the failed record and retried with a delay; this is at-least-once delivery, so handlers should be idempotent. EnableAutoCommit is retained for configuration compatibility, but LinKit disables broker auto-commit to avoid acknowledging unprocessed records.

Kafka uses MessageHeaderNames.PartitionKey as the record key when present; otherwise it uses the producer's routingKey. The Outbox publisher supplies the Outbox message ID by default to avoid putting every message for a topic on one partition. Set the partition-key header to a stable aggregate key when per-aggregate ordering is required.

For trimmed or Native AOT applications, define and register a System.Text.Json source-generated context containing every message type used by producers and consumers:

using System.Text.Json.Serialization;
using LinKit.Core.Messaging;

[JsonSerializable(typeof(OrderCreated))]
internal partial class AppMessageJsonContext : JsonSerializerContext;

LinKitMessageJson.AddContext(AppMessageJsonContext.Default);

Register the context before publishing or starting consumers. A reflection fallback may be available when dynamic code is enabled; do not rely on it in Native AOT.

2. Register Services in Program.cs

In your application's startup code (e.g., Program.cs for a Worker Service), use the AddLinKitKafka() extension method after registering the core LinKit services.

using LinKit.Core;
using LinKit.Messaging.Kafka;

var builder = Host.CreateApplicationBuilder(args);

// 1. Register core LinKit services.
// This generates the IMessagePublisher and your consumer IHostedService(s).
builder.Services.AddLinKitCqrs();
builder.Services.AddLinKitMessaging();

// 2. Provide the Kafka implementation.
// This "plugs in" Kafka to the generated services.
builder.Services.AddLinKitKafka(builder.Configuration);

var host = builder.Build();
host.Run();

AddLinKitKafka registers the IBrokerProducer and IBrokerConnection implementations. Offset commits occur after successful handler completion; failures seek back and retry. Delivery is at-least-once, so consumers should be idempotent. Publishing to a DLQ and committing the source offset are not one atomic transaction; a crash can duplicate a DLQ record.

License

MIT. See the repository license.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.5.1 89 11/8/2026
1.3.1 112 10/31/2026
1.3.0 97 10/30/2026
1.2.0 101 10/22/2026
1.1.0 106 10/20/2026
1.0.0 334 8/29/2025

v1.5.1: documentation and packaging patch - every public member now carries XML documentation (CS1591 is enforced as a build error) and the README was reviewed for accuracy. Previous release: v1.5.0 - KafkaOptions are validated through IValidateOptions - an empty BootstrapServers or GroupId, a non-positive BatchSize or a negative attempt/linger setting fails at startup instead of degrading at runtime. Full documentation & release notes: https://quoclinh.id.vn/docs/linkit