AvroSharp 1.0.0

AvroSharp

A high-performance .NET implementation of the Apache Avro™ specification: schemas, binary and JSON encoding, schema resolution, object container files and single-object encoding. It is written for spans and IBufferWriter<byte>, allocates little, and needs no reflection, so it works with Native AOT and trimming.

Status: stable. The public API follows semantic versioning: no breaking changes before 2.0.

Documentation · API reference · Code generation · Benchmarks · Compared with Apache.Avro

Targets net10.0, net9.0, net8.0, netstandard2.1 and netstandard2.0.

Getting started

Parse a schema with AvroSchema.Parse, then write and read values of it with the generic data model: GenericDatumWriter and GenericDatumReader. AvroValue holds any Avro value without boxing, and a GenericRecord holds a record's fields by name or position.

using AvroSharp.Generic;
using AvroSharp.Schemas;

var schema = (RecordSchema)AvroSchema.Parse("""
    {"type":"record","name":"User","namespace":"example","fields":[
      {"name":"id","type":"int"},
      {"name":"name","type":"string"}]}
    """);

var user = new GenericRecord(schema) { ["id"] = 1, ["name"] = "Ada" };
byte[] bytes = GenericDatumWriter.Create(schema).WriteToArray(user);

GenericRecord copy = GenericDatumReader.Create(schema).Read(bytes).AsRecord();

Schema evolution. Data written with one version of a schema can be read as another: GenericDatumReader.Create(writerSchema, readerSchema). Fields are matched by name or alias, removed fields are skipped, added fields take their defaults, and numbers are promoted. Readers and writers are cached per schema (or schema pair) and are thread-safe.

JSON. GenericDatumJsonWriter and GenericDatumJsonReader implement the specification's JSON encoding.

Object container files

AvroFileWriter writes .avro files and AvroFileReader reads them:

using var writer = AvroFileWriter.CreateGeneric(stream, schema, new AvroFileWriterOptions { Codec = AvroCodec.Deflate });
writer.Write(user);

using var reader = AvroFileReader.OpenGeneric(stream);
foreach (var value in reader.ReadAll()) { ... }

Asynchronous reading and writing are available too (OpenGenericAsync, ReadAllAsync). null and deflate are built in (AvroCodec, DeflateCodec); the AvroSharp.Codecs package adds snappy, zstandard, bzip2 and xz.

Single-object encoding, schema registries and streams

AvroMessage and AvroMessageReader write and read single-object encoded messages, with a schema store (AvroSchemaStore, or your own IAvroSchemaResolver) that finds the writer schema by fingerprint. AvroRegistryMessage and AvroRegistryMessageReader write and read messages in a schema registry's framing, with a schema ID instead of the fingerprint (AvroRegistryFraming: Confluent, Apicurio, AWS Glue). AvroStreamWriter and AvroStreamReader handle a stream of values without a container.

C# types from schema files

The AvroSharp.Generators package generates C# classes from .avsc files at build time, with serializers that call AvroWriter/AvroReader directly:

byte[] bytes = order.ToAvroBytes();
var copy = shop.Order.FromAvroBytes(bytes);

More

• Documentation and samples
• Changelog
• Third-party notices (also in the package)
• Licensed under the MIT license.