Optima.Net.Events 1.0.2

Optima.Net.Events

A self-validating event serialization framework for .NET supporting Avro and Protobuf.
It provides schema-driven serialization, payload normalization, and forward/backward compatibility for distributed event-driven systems.

If you like what I did here or it inspired you to learn something new, please consider buying me a coffee: https://buymeacoffee.com/snamretsuek The support would be greatly appreciated!

Overview

Optima.Net.Events enables schema-safe event exchange between microservices using either Avro or Protobuf.
It handles field normalization, schema validation, and ensures your events remain compatible across versions.

Features

Core Capabilities

• Generic event model with dynamic payloads (GenericEvent<TPayload> and DynamicPayload)
• Self-validating Avro-based serialization and deserialization
• Schema generation for both Avro (.avsc) and Protobuf (.proto)
• Payload normalization that ensures Avro and Protobuf-safe field names
• Optional<T> support with built-in JSON converters
• Backward and forward compatibility handling
• Case-insensitive deserialization and graceful handling of missing fields

Example: Avro Event Serialization

var payload = new DynamicPayload("PaymentRequested");
payload.Add("SourceAccountNumber", "123456789");
payload.Add("TargetAccountNumber", "987654321");
payload.Add("Amount", 1500.75);
payload.Add("Currency", "USD");

var evt = new GenericEvent<DynamicPayload>
{
    EventId = Guid.NewGuid(),
    EventType = payload.PayloadName,
    Source = "PaymentsService",
    SchemaVersion = "V1.0.0",
    Timestamp = DateTime.UtcNow,
    Payload = payload
};

// Generate Avro schema
var schemaJson = AvroSchemaGenerator.GenerateSchemaFromGenericEvent(evt);
Console.WriteLine(schemaJson);

// Serialize and deserialize
var data = AvroEventSerializer.Serialize(evt, schemaJson);
var result = AvroEventSerializer.Deserialize(data, schemaJson);

// Output event before and after serialization
Console.WriteLine(JsonHelper.Serialize(evt, true));
Console.WriteLine(JsonHelper.Serialize(result, true));

Example: Protobuf Event Serialization

var payload = new DynamicPayload("PaymentRequested");
payload.Add("SourceAccountNumber", "123456789");
payload.Add("SourceFirstName", "Marcus");
payload.Add("SourceLastName", "Keulen");
payload.Add("TargetAccountNumber", "987654321");
payload.Add("TargetFirstName", "Jane");
payload.Add("Amount", "1500.75");
payload.Add("Currency", "USD");

var evt = new GenericEvent<DynamicPayload>
{
    EventId = Guid.NewGuid(),
    EventType = payload.PayloadName,
    Source = "PaymentsService",
    SchemaVersion = "V1.0.0",
    Timestamp = DateTime.UtcNow,
    Payload = payload
};

// Generate Protobuf schema
var protoSchema = ProtobufSchemaGenerator.GenerateSchemaProto(payload.Fields, payload.PayloadName);

// Serialize
var data = ProtobufEventSerializer.Serialize(evt);

// Deserialize (requires schema)
var result = ProtobufEventSerializer.Deserialize<DynamicPayload>(data, protoSchema);

// Print results
Console.WriteLine(JsonHelper.Serialize(evt, true));
Console.WriteLine(JsonHelper.Serialize(result, true));

CLI Schema Generation

It is strongly recommended that developers implement a CLI utility using the schema generator functions to pre-generate schemas for all events.

You can then store these .avsc or .proto files in a central schema directory or registry.
At runtime, your services can retrieve these schemas and pass them to the relevant serializer methods.

Example CLI command concept:

dotnet run -- generate-schema --type PaymentRequested --output ./schemas

This ensures:

• Consistent schema evolution across all services
• Reproducible serialization and deserialization
• Safe backward and forward compatibility

Comparison

You should do your own benchmark testing. Those execution times are not cast in stone and depend greatly on how your event is structured. This times were recoded using the Event, in the excamples.

Planned Modules

• Optima.Net.Events.Kafka � native Kafka producer/consumer support using Avro and Protobuf.
• Schema Registry Integration � automatic schema storage and retrieval.
• Automatic Schema Hashing and Version Matching � ensure schema alignment between services.

Compatibility

• .NET 8.0 or later
• Cross-platform: Windows, Linux, macOS

License

MIT License � 2025