Messaging Model

Summary — Mapping POCOs to Kafka messages

Ksql.Linq maps your POCO classes to Kafka key/value messages and handles serialization (Avro) and deserialization for you.

• Produce: POCO → Avro → Kafka
• Consume: Kafka → Avro → POCO

Goal: let you design topics and messages at the application level, while keeping message I/O strongly typed and predictable.

Concepts

• Shape with POCOs: express business data as simple DTOs
• Keys: choose stable key properties on your DTO for partitioning and compaction
• I/O: write/read DTOs as Kafka key/value; the framework performs (de)serialization
• Schema: Avro schemas for key/value are generated/registered and kept in sync

POCO attributes

• [KsqlTopic]: bind a POCO to a Kafka topic name
• [KsqlKey]: mark one or more properties as the message key
• [KsqlTimestamp]: designate the event time (used by Avro/ksqlDB)
• [KsqlTable]: mark entities that are materialized as TABLEs (default is STREAM)
• [KsqlDecimal]: opt‑in decimal support mapped to Avro logical type

Example

using Ksql.Linq.Core.Attributes;

[KsqlTopic("basic-produce-consume")]
public class BasicMessage
{
    [KsqlKey] public int Id { get; set; }
    [KsqlTimestamp] public DateTime CreatedAt { get; set; }
    public string Text { get; set; } = string.Empty;
}

Design notes

• Keep DTOs stable: manage schema evolution deliberately (prefer additive changes)
• Keys and partitions: use keys that match your access patterns; avoid null keys when compaction is required
• Separation of concerns: keep POCOs in a shared contracts project if multiple apps produce/consume them
• Schema governance: coordinate POCO changes with Schema Registry compatibility modes and KSQL DDL

Related

• Architecture-Overview
• Kafka-Ksql-Linq-User-Guide
• Produce-Consume-and-DLQ
• Appsettings

Sample code

• Attribute examples: /examples/schema-attributes/Program.cs
• Headers and metadata: /examples/headers-meta/Program.cs
• Basic produce/consume: /examples/basic-produce-consume/Program.cs