Serialization Formats

KafkaWorker supports four serialization formats via separate NuGet packages. All formats default to string keys — use the 3-type-parameter overload if you need a custom key type.

Table of contents

1. Overview
2. Plain JSON
3. Avro
4. Protobuf
5. JSON with Schema Registry
6. Custom Key Types
7. Schema Registry Client Sharing

---

Overview

Method	Package	Use Case
AddKafkaWorker	KafkaWorker	Plain JSON (System.Text.Json) — no Schema Registry needed
AddKafkaWorkerAvro	KafkaWorker.Avro	Avro messages with Schema Registry
AddKafkaWorkerProtobuf	KafkaWorker.Protobuf	Protobuf messages with Schema Registry (must implement IMessage<T>)
AddKafkaWorkerRegistryJson	KafkaWorker.JsonSchema	JSON messages with Schema Registry

Schema Registry formats require SchemaRegistryUrls in the connection config. The registry client is shared automatically when multiple formats are registered in the same host.

---

Plain JSON

The default format — messages are consumed as raw strings from Kafka and deserialized using System.Text.Json.JsonSerializer. No Schema Registry needed.

dotnet add package KafkaWorker

builder.Services.AddKafkaWorker<OrderMessage, OrderMessageHandler>(builder.Configuration);

---

Avro

Uses Confluent’s Avro deserializer with Schema Registry. Your message type must be generated from an Avro schema.

dotnet add package KafkaWorker.Avro

builder.Services.AddKafkaWorkerAvro<OrderMessage, OrderMessageHandler>(builder.Configuration);

Requires SchemaRegistryUrls in the connection config:

{
  "KafkaWorker": {
    "Connection": {
      "BootstrapServers": "localhost:9092",
      "SchemaRegistryUrls": "http://schema-registry:8081"
    }
  }
}

---

Protobuf

Uses Confluent’s Protobuf deserializer with Schema Registry. Your message type must implement Google.Protobuf.IMessage<T>.

dotnet add package KafkaWorker.Protobuf

builder.Services.AddKafkaWorkerProtobuf<OrderMessage, OrderMessageHandler>(builder.Configuration);

---

JSON with Schema Registry

Uses Confluent’s JSON Schema deserializer with Schema Registry for schema validation.

dotnet add package KafkaWorker.JsonSchema

builder.Services.AddKafkaWorkerRegistryJson<OrderMessage, OrderMessageHandler>(builder.Configuration);

---

Custom Key Types

All registration methods have a 3-type-parameter overload for custom key types:

// Plain JSON with Guid keys
builder.Services.AddKafkaWorker<Guid, OrderMessage, OrderMessageHandler>(builder.Configuration);

// Avro with string keys (explicit)
builder.Services.AddKafkaWorkerAvro<string, OrderMessage, OrderMessageHandler>(builder.Configuration);

When using the 2-type-parameter overload (<TMessage, THandler>), the key type defaults to string.

---

Schema Registry Client Sharing

When you register multiple consumers that use Schema Registry (Avro, Protobuf, or JSON Schema), the library automatically shares a single CachedSchemaRegistryClient instance across all registrations. You don’t need to configure anything — the first registration creates the client, and subsequent registrations reuse it.