Interface IConfluentFormatSerializer
Serializes messages to Confluent wire format (magic byte + schema ID + payload).
public interface IConfluentFormatSerializer
- Extension Methods
Remarks
Implementations produce byte arrays in the Confluent wire format:
- Byte 0: Magic byte (0x00)
- Bytes 1-4: Schema ID (big-endian 32-bit integer)
- Bytes 5+: Serialized message payload
The schema is automatically registered with the Schema Registry if not already present.
Zero-Copy Support: The SerializeToBufferAsync methods
provide zero-copy serialization by writing directly to an IBufferWriter<T>,
eliminating intermediate byte[] allocations in the hot path.
Methods
SerializeAsync(string, object, Type, CancellationToken)
Serializes a message to Confluent wire format using a runtime type.
Task<byte[]> SerializeAsync(string topic, object message, Type messageType, CancellationToken cancellationToken)
Parameters
topicstringThe Kafka topic name (used for subject naming).
messageobjectThe message to serialize.
messageTypeTypeThe runtime type of the message.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
Remarks
This overload is useful when the message type is only known at runtime,
such as when dispatching IDispatchAction instances.
Exceptions
- SchemaRegistryException
Schema registration failed or the schema is incompatible with existing versions.
SerializeAsync<T>(string, T, CancellationToken)
Serializes a message to Confluent wire format.
Task<byte[]> SerializeAsync<T>(string topic, T message, CancellationToken cancellationToken)
Parameters
topicstringThe Kafka topic name (used for subject naming).
messageTThe message to serialize.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
Type Parameters
TThe type of message to serialize.
Exceptions
- SchemaRegistryException
Schema registration failed or the schema is incompatible with existing versions.
SerializeToBufferAsync(IBufferWriter<byte>, string, object, Type, CancellationToken)
Serializes a message to Confluent wire format directly into a buffer writer using a runtime type (zero-copy).
ValueTask<int> SerializeToBufferAsync(IBufferWriter<byte> writer, string topic, object message, Type messageType, CancellationToken cancellationToken)
Parameters
writerIBufferWriter<byte>The buffer writer to write the serialized data to.
topicstringThe Kafka topic name (used for subject naming).
messageobjectThe message to serialize.
messageTypeTypeThe runtime type of the message.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
Remarks
This overload is useful when the message type is only known at runtime,
such as when dispatching IDispatchAction instances.
This method provides zero-copy serialization by writing the 5-byte Confluent header and JSON payload directly to the provided buffer, eliminating intermediate allocations.
Exceptions
- ArgumentNullException
Thrown when
writer,message, ormessageTypeis null.- ArgumentException
Thrown when
topicis null, empty, or whitespace.- SchemaRegistryException
Schema registration failed or the schema is incompatible with existing versions.
SerializeToBufferAsync<T>(IBufferWriter<byte>, string, T, CancellationToken)
Serializes a message to Confluent wire format directly into a buffer writer (zero-copy).
ValueTask<int> SerializeToBufferAsync<T>(IBufferWriter<byte> writer, string topic, T message, CancellationToken cancellationToken)
Parameters
writerIBufferWriter<byte>The buffer writer to write the serialized data to.
topicstringThe Kafka topic name (used for subject naming).
messageTThe message to serialize.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
Type Parameters
TThe type of message to serialize.
Examples
using var bufferWriter = new PooledBufferWriter();
var bytesWritten = await serializer.SerializeToBufferAsync(bufferWriter, "orders-topic", order, ct);
var data = bufferWriter.WrittenMemory;
Remarks
This method provides zero-copy serialization by writing the 5-byte Confluent header and JSON payload directly to the provided buffer, eliminating intermediate allocations.
The caller is responsible for providing a properly sized buffer writer
(e.g., PooledBufferWriter or PipeWriter).
Exceptions
- ArgumentNullException
Thrown when
writerormessageis null.- ArgumentException
Thrown when
topicis null, empty, or whitespace.- SchemaRegistryException
Schema registration failed or the schema is incompatible with existing versions.