AvroSourceGenerator 0.1.0-preview.6

Avro Source Generator

Avro Source Generator is a .NET source generator that generates C# code from Avro schemas.

It produces models that use modern C# features, such as nullable reference types, init-only properties, required properties, and more.

Prerequisites

• .NET SDK 8.0 or later

Usage

To use the Avro Source Generator in your project, add a reference to the AvroSourceGenerator package in your .csproj file. Since it generated code compatible with Apache.Avro, make sure you also add that package:

dotnet add package AvroSourceGenerator
dotnet add package Apache.Avro

You can mark the AvroSourceGenerator package as PrivateAssets="all" to prevent projects referencing yours from getting a reference to it. Additionally, use ExcludeAssets="runtime" to ensure that AvroSourceGenerator.Attributes is not copied to the build output, since it is not required at runtime.

<PackageReference Include="AvroSourceGenerator" Version="*" PrivateAssets="all" ExcludeAssets="runtime" />

Then, configure the .csproj to include Avro schema files as AdditionalFiles.

<ItemGroup>
  <AdditionalFiles Include="schemas/*.avsc" />
</ItemGroup>

Add the schema file to your project.

schemas/user.avsc

{
  "type": "record",
  "name": "User",
  "namespace": "example",
  "fields": [
    {
      "name": "Name",
      "type": "string"
    },
    {
      "name": "Email",
      "type": [
          "null",
          "string"
      ]
    },
    {
      "name": "CreatedAt",
      "type": {
          "type": "long",
          "logicalType": "timestamp-millis"
      }
    }
  ]
}

This will generate the C# files containing the types defined in the Avro schema.

Here is an example of a generated class for the User schema defined above:

// <auto-generated/>
#pragma warning disable CS8618, CS8633, CS8714, CS8775
#nullable enable
namespace example
{
    [global::System.CodeDom.Compiler.GeneratedCode("AvroSourceGenerator", "1.0.0.0")]
    public partial record User : global::Avro.Specific.ISpecificRecord
    {
        public required string Name { get; init; }
        public string? Email { get; init; }
        public required global::System.DateTime CreatedAt { get; init; }
    
        public global::Avro.Schema Schema { get => User._SCHEMA; }
        public static readonly global::Avro.Schema _SCHEMA = global::Avro.Schema.Parse("""
        {
          "type": "record",
          "namespace": "example",
          "name": "User",
          "fields": [
            {
              "name": "Name",
              "type": "string"
            },
            {
              "name": "Email",
              "type": [
                "null",
                "string"
              ]
            },
            {
              "name": "CreatedAt",
              "type": {
                "type": "long",
                "logicalType": "timestamp-millis"
              }
            }
          ]
        }
        """);
    
        public object? Get(int fieldPos)
        {
            switch (fieldPos)
            {
                case 0: return this.Name;
                case 1: return this.Email;
                case 2: return this.CreatedAt;
                default: throw new global::Avro.AvroRuntimeException($"Bad index {fieldPos} in Get()");
            }
        }
        
        public void Put(int fieldPos, object? fieldValue)
        {
            switch (fieldPos)
            {
                case 0:
                    Set_Name(this, (string)fieldValue!); break;
                    [global::System.Runtime.CompilerServices.UnsafeAccessor(global::System.Runtime.CompilerServices.UnsafeAccessorKind.Method, Name = "set_Name")]
                    extern static void Set_Name(User obj, string value);
                case 1:
                    Set_Email(this, (string?)fieldValue!); break;
                    [global::System.Runtime.CompilerServices.UnsafeAccessor(global::System.Runtime.CompilerServices.UnsafeAccessorKind.Method, Name = "set_Email")]
                    extern static void Set_Email(User obj, string? value);
                case 2:
                    Set_CreatedAt(this, (global::System.DateTime)fieldValue!); break;
                    [global::System.Runtime.CompilerServices.UnsafeAccessor(global::System.Runtime.CompilerServices.UnsafeAccessorKind.Method, Name = "set_CreatedAt")]
                    extern static void Set_CreatedAt(User obj, global::System.DateTime value);
                default:
                    throw new global::Avro.AvroRuntimeException($"Bad index {fieldPos} in Put()");
            }
        }
    }

}
#nullable restore
#pragma warning restore CS8618, CS8633, CS8714, CS8775

Extending generated code

Generated types are partial. This allows extending them using another partial definition.

Example for the User type generated above.

namespace example;

public partial record User
{
    public override string ToString() => Name;
}

Access modifier

By default, types are generated as public.

To change the access modifier of all generated types, add AvroSourceGeneratorAccessModifier to your .csproj.

<PropertyGroup>
  <AvroSourceGeneratorAccessModifier>internal</AvroSourceGeneratorAccessModifier>
</PropertyGroup>

Supported values are public (default) and internal.

To change the access modifier of just one type, declare a partial definition for it using the desired access modifier, and annotate it with the Avro attribute.

using AvroSourceGenerator;

namespace example;

[Avro]
internal partial record User;

Records

By default, generated code will prefer record declarations where possible.

To change the preference for all generated types, add AvroSourceGeneratorRecordDeclaration to your .csproj.

<PropertyGroup>
  <AvroSourceGeneratorRecordDeclaration>class</AvroSourceGeneratorRecordDeclaration>
</PropertyGroup>

Supported values are record (default) and class.

To change the declaration of just one type, declare a partial definition for it using the desired record or class keyword, and annotate it with the Avro attribute.

using AvroSourceGenerator;

namespace example;

[Avro]
public partial class User;

Language features

By default, code will be generated with the latest features available to the consuming project.

It is possible to specify the C# language features to be used in the generated code. This is useful when you need to ensure compatibility with older versions of C#.
For example, using LanguageFeatures.CSharp7_3 will generate code using only features that are compatible with C# 7.3 (e.g., no nullable reference types, no records, etc).

To change language features for all generated code, add AvroSourceGeneratorLanguageFeatures to your .csproj.

<PropertyGroup>
  <AvroSourceGeneratorLanguageFeatures>CSharp7_3</AvroSourceGeneratorLanguageFeatures>
</PropertyGroup>

Supported values are all flags defined in the LanguageFeatures enum.
Parsing is case insensitive and uses default rules for flags (it uses Enum.Parse).

To change used features for just one type, declare a partial definition for it, and annotate it with the Avro attribute, specifying a LanguageFeatures argument.

using AvroSourceGenerator;

namespace example;

[Avro(LanguageFeatures = LanguageFeatures.CSharp7_3)]
public partial record User;

It is also possible to enable or disable specific features.

Example for using the latest features but excluding required properties:

using AvroSourceGenerator;

namespace example;

[Avro(LanguageFeatures = LanguageFeatures.Latest & ~LanguageFeatures.RequiredProperties)]
public partial record User;

Limitations

In C#, enum types cannot be declared as partial, so it's not possible to configure code generation for just a single enum type.
A possible workaround for this is to wrap the enum schema in a record schema.

<details> <summary> Example </summary>

Before

Suit.avsc

{
  "type": "enum",
  "name": "Suit",
  "namespace": "example",
  "symbols": [
    "Hearts",
    "Diamonds",
    "Clubs",
    "Spades"
  ]
}

Suit.Avro.g.cs

// <auto-generated/>
namespace example
{
    [global::System.CodeDom.Compiler.GeneratedCode("AvroSourceGenerator", "1.0.0.0")]
    public enum Suit
    {
        Hearts,
        Diamonds,
        Clubs,
        Spades,
    }
}

After

SuitWrapper.avsc

{
  "type": "record",
  "name": "SuitWrapper",
  "namespace": "example",
  "fields": [
    {
      "name": "WrapperField",
      "type": {
        "type": "enum",
        "name": "Suit",
        "namespace": "example",
        "symbols": [
          "Hearts",
          "Diamonds",
          "Clubs",
          "Spades"
        ]
      }
    }
  ]
}

SuitWrapper.cs

using AvroSourceGenerator;

namespace example;

[Avro]
internal partial record SuitWrapper;

Suit.Avro.g.cs

// <auto-generated/>
namespace example
{
    [global::System.CodeDom.Compiler.GeneratedCode("AvroSourceGenerator", "1.0.0.0")]
    internal enum Suit
    {
        Hearts,
        Diamonds,
        Clubs,
        Spades,
    }
}

</details>

Contributing

Contributions are welcome! If you have any ideas, suggestions, or bug reports, please open an issue or submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.