Compiler

FlatSharp can be run at build-time with the FlatSharp.Compiler NuGet package. The compiler accepts fbs files and produces C# at build time. The FlatSharp compiler targets netcoreapp3.1, net5.0, and net6.0, which are just the runtimes necessary to execute the compiler, and has no bearing on the code the compiler generates. The FlatSharp compiler generates code that can run inside .NET Framework, .NET Standard 2.0+, or .NET Core 2.1+.

Adding FBS files (MSBuild)

FBS files must be opted into the compiler:

<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <FlatSharpSchema Include="YourSchema.fbs" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="FlatSharp.Compiler" Version="5.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
    <PackageReference Include="FlatSharp.Runtime" Version="5.0.0" />
  </ItemGroup>
</Project>

Command Line Invocation

While .csproj files offer MSBuild integration, you may also choose to invoke the FlatSharp compiler yourself. The syntax is relatively straightforward:

dotnet FlatSharp.Compiler.dll -i <input_fbs_file> -o <output directory>

Additionally, the FlatSharp compiler supports some optional arguments:

• --nullable-warnings: Enables nullability warnings
• --normalize-field-names: Enables field name normalization to standard C# style.
• --includes path1;path2;path3: Passes include search paths to flatc.

Unity

Unity does not allow modification of the .csproj file, which makes the above difficult. For Unity users, the best current option is to invoke the compiler manually in a prebuild step.

Nullable Annotations

By default, the FlatSharp compiler inherits the project setting for nullable annotations. If <Nullable> is set to enabled in the project, then FlatSharp will generate code with full nullable attributes and annotations. If <Nullable> is set to anything besides enabled in the project, FlatSharp will generate code with nullable annotations only.

Full nullable annotations may only work correctly with C# 9 and above.

This behavior can be overridden with the <FlatSharpNullable> property.

  <!-- Flatsharp inherits the project setting and generates full nullable code -->
  <PropertyGroup>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <!-- FlatSharp only generates nullable annotations (no attributes/warnings) -->
  <PropertyGroup>
    <Nullable>enable</Nullable>
    <FlatSharpNullable>false</FlatSharpNullable>
  </PropertyGroup>

  <!-- FlatSharp only generates nullable annotations (no attributes/warnings) -->
  <PropertyGroup>
    <Nullable>disable</Nullable>
  </PropertyGroup>

  <!-- Flatsharp overrides the project setting and generates full nullable code -->
  <PropertyGroup>
    <Nullable>disable</Nullable>
    <FlatSharpNullable>true</FlatSharpNullable>
  </PropertyGroup>

Include Search Paths

The FlatSharp Compiler is built on top of flatc, the official compiler. flatc supports passing in search paths to find imported fbs files. Include Paths may be specified per FBS file:

    <FlatSharpSchema Include="Example07-Includes\**\*.fbs">
      <IncludePath>Example07-Includes</IncludePath>
    </FlatSharpSchema>

PascalCase Normalization

FlatBuffers schemas canonically use snake_case for fields. FlatSharp exposes an optional switch to normalize these to UpperPascalCase.

  <PropertyGroup>
    <FlatSharpNameNormalization>true</FlatSharpNameNormalization>
  </PropertyGroup>

This feature is disabled by default, since it would be a breaking change for any existing users. However, this will become the default behavior in the next major version of FlatSharp.