DOCSEARCHbyAlgolia
Submit Docs

FlatSharp Documentation

repository·main·Indexed 20 days ago

https://github.com/jamescourtney/flatsharp

A high-performance, zero-copy binary serialization format for C# based on Google's FlatBuffers. Designed for speed, safety, and compatibility with Memory<T>, Span<T>, and AOT scenarios such as Unity, Blazor, and Xamarin. It utilizes a build-time compiler (FlatSharp.Compiler) and runtime library (FlatSharp.Runtime) to generate C# subclasses from .fbs schema files.

Tokens
1.1K
Snippets
7
Records
8
Agent score
19%

What's inside FlatSharp

  1. How FlatSharp works: Generated subclasses

    main
    FlatSharp operates by generating C# subclasses of your data contracts based on your .fbs schema. When you deserialize a table (e.g., MonsterTable), you receive an instance of a generated subclass. This subclass contains properties designed to index directly into the underlying memory buffer according to your chosen deserialization mode (such as Lazy or Greedy).

  2. Install FlatSharp via NuGet

    main

    To use FlatSharp, you must reference two specific packages from NuGet. Ensure you use the same version for both to maintain compatibility.

    • FlatSharp.Runtime: The core runtime library required for all projects using FlatSharp.
    • FlatSharp.Compiler: The build-time compiler used to generate C# code from your .fbs schema files.
    Reference both FlatSharp.Runtime and FlatSharp.Compiler from NuGet. Use the same version for both.

  3. Configure FlatSharp Schema in .csproj

    main

    To integrate your schema into the build process, add a FlatSharpSchema item to your .csproj file pointing to your .fbs file. This allows the compiler to generate the necessary C# code.

    <ItemGroup>
  <FlatSharpSchema Include="YourSchema.fbs" />
</ItemGroup>

  4. Integrate FlatSharp schema into your .csproj

    main

    To trigger the code generation process during build, add the FlatSharpSchema item to your .csproj file, pointing to your .fbs schema file.

    <ItemGroup>
  <FlatSharpSchema Include="YourSchema.fbs" />
</ItemGroup>

  5. Define a FlatBuffer schema with FlatSharp attributes

    main

    FlatSharp uses standard FlatBuffer IDL (Interface Definition Language). To enable FlatSharp-specific features like automatic serializer generation, use attributes prefixed with fs_.

    Example schema defining a Person table with a fs_serializer attribute:

    // all FlatSharp FBS attributes start with the 'fs_' prefix.
attribute "fs_serializer";

namespace MyNamespace;

enum Color : ubyte { Red = 1, Green, Blue }

table Person (fs_serializer) {
    id : int;
    name : string;
    parent : Person (deprecated);
    children : [ Person ];
    favorite_color : Color = Blue;
    position : Location;
}

struct Location {
    latitude : float;
    longitude : float;
}

  6. Define a FlatSharp Schema

    main

    FlatSharp uses FlatBuffers IDL. Note that all FlatSharp-specific attributes must be prefixed with fs_. For example, to enable serialization for a table, use the fs_serializer attribute.

    // all FlatSharp FBS attributes start with the 'fs_' prefix.
attribute "fs_serializer";

namespace MyNamespace;

enum Color : ubyte { Red = 1, Green, Blue }

table Person (fs_serializer) {
    Id:int;
    Name:string;
    Parent:Person (deprecated);
    Children:[Person];
    FavoriteColor:Color = Blue;
    Position:Location;
}

struct Location {
    Latitude:float;
    Longitude:float;
}

  8. Serialize data with FlatSharp

    main

    To serialize an object, use the generated Serializer property on your type. You should first call GetMaxSize to determine the required buffer size, then call Serialize to write the data into a byte array.

    Person person = new Person(...);
int maxBytesNeeded = Person.Serializer.GetMaxSize(person);
byte[] buffer = new byte[maxBytesNeeded];
int bytesWritten = Person.Serializer.Serialize(buffer, person);